跳转到正文

Resources、内容与生命周期 ​

行为与约束 ​

普通 buffer 在此基线只支持 persistent,usage 为 staticDraw / dynamicDraw / streamDraw;content 只接受 undefined、generated 或 service,v5 另有 materialTable。asset/clear/external 不能用于普通 buffer,即使通用 Schema 的 content 分支包含它们。undefined 的活动读者仍需要生产者。materialTable 的每个消费者必须是只读 SSBO,不能作为 UBO,详见完整反例。

资源 id 在候选内解析。kind 为 texture2D、textureCube 或 buffer。纹理 size 使用 absolute 的 width/height、viewport 或 output 及适用 scale;buffer 使用 byteSize 和 usage,不套用纹理 format/size。颜色/深度格式、bytesPerPixel 与版本见 Catalog;容量估算不含驱动开销。

lifetime 为 persistent、frame、transient、history、external。history 可用对象 kind/capacity 或适用的 historyCapacity,容量至少 2;环槽的 current/previous 和 framesAgo 需满足容量及 view 合同。historyCommit 是提交事件;帧边界推进一次,禁用 producer 不伪造新历史。resize、generation/device 等失效不能靠采样旧槽恢复。

content 可为 undefined/external,或 clear、asset、generated、service;v5 增加 materialTable。undefined 不保证初值为零。clear 的 value 形状须匹配资源;asset 的 path 与 cube 六面 faces 二选一,encoding 为 image/raw,实际格式和尺寸还受 Loader/初始化器约束。generated 的 generator/version、service 的 service/version 必须与活动 Service 的内容提供能力一致;仅写一个 Catalog ID 不会创建任意 C# 工厂。materialTable 只能用于支持的 buffer,容量由最终布局计算,不手填 byteSize。

未声明 sampling 时保留 nearest、repeat、单 mip 默认。显式 minFilter/magFilter、wrapS/wrapT、mipLevels 仍需资源类型、格式及实际上传支持;image asset 的解码尺寸必须与声明一致。comparison sampling 另有严格组合,不会改写纹理采样合同。

事务顺序是活动闭包 → 分配候选资源/view/FBO → allocator clear/asset → 创建和初始化 Services → generated/service content → Program 验证 → 整体发布。回滚先反序退出 Services 再释放候选资源;不能从旧活动 generation 借一半资源来补齐候选。

自动生成的 v5 结构 ​

必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。

resource · v5 ​

字段 / 分支本对象必需性结构约束
oneOf[0].contentoptional here$ref="#/$defs/content"
oneOf[0].formatoptional here$ref="#/$defs/nonEmptyString"
oneOf[0].historyCapacityoptional heretype="integer"; minimum=2
oneOf[0].idrequired$ref="#/$defs/identifier"
oneOf[0].kindrequiredenum=["texture2D","textureCube"]
oneOf[0].lifetimerequiredoneOf: 2
oneOf[0].samplingoptional here$ref="#/$defs/sampling"
oneOf[0].sizeoptional here$ref="#/$defs/size"
oneOf[1].byteSizeoptional heretype="integer"; minimum=1
oneOf[1].contentoptional here$ref="#/$defs/content"
oneOf[1].idrequired$ref="#/$defs/identifier"
oneOf[1].kindrequiredconst="buffer"
oneOf[1].lifetimerequiredoneOf: 2
oneOf[1].usageoptional hereenum=["staticDraw","dynamicDraw","streamDraw"]
完整结构规则: #/$defs/resource
json
{
  "oneOf": [
    {
      "additionalProperties": false,
      "allOf": [
        {
          "not": {
            "allOf": [
              {
                "properties": {
                  "content": {
                    "allOf": [
                      {
                        "properties": {
                          "type": {
                            "const": "materialTable"
                          }
                        },
                        "required": [
                          "type"
                        ]
                      }
                    ],
                    "type": "object"
                  }
                }
              }
            ],
            "required": [
              "content"
            ]
          }
        }
      ],
      "properties": {
        "content": {
          "$ref": "#/$defs/content"
        },
        "format": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "historyCapacity": {
          "minimum": 2,
          "type": "integer"
        },
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "kind": {
          "enum": [
            "texture2D",
            "textureCube"
          ]
        },
        "lifetime": {
          "oneOf": [
            {
              "enum": [
                "persistent",
                "frame",
                "transient",
                "history",
                "external"
              ]
            },
            {
              "$ref": "#/$defs/historyLifetime"
            }
          ]
        },
        "sampling": {
          "$ref": "#/$defs/sampling"
        },
        "size": {
          "$ref": "#/$defs/size"
        }
      },
      "required": [
        "id",
        "kind",
        "lifetime"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "allOf": [
              {
                "properties": {
                  "content": {
                    "allOf": [
                      {
                        "properties": {
                          "type": {
                            "const": "materialTable"
                          }
                        },
                        "required": [
                          "type"
                        ]
                      }
                    ],
                    "type": "object"
                  }
                }
              }
            ],
            "required": [
              "content"
            ]
          },
          "then": {
            "not": {
              "anyOf": [
                {
                  "required": [
                    "byteSize"
                  ]
                }
              ]
            }
          }
        },
        {
          "else": {
            "required": [
              "byteSize"
            ]
          },
          "if": {
            "allOf": [
              {
                "properties": {
                  "content": {
                    "allOf": [
                      {
                        "properties": {
                          "type": {
                            "const": "materialTable"
                          }
                        },
                        "required": [
                          "type"
                        ]
                      }
                    ],
                    "type": "object"
                  }
                }
              }
            ],
            "required": [
              "content"
            ]
          },
          "then": {
            "required": [
              "content"
            ]
          }
        }
      ],
      "properties": {
        "byteSize": {
          "minimum": 1,
          "type": "integer"
        },
        "content": {
          "$ref": "#/$defs/content"
        },
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "kind": {
          "const": "buffer"
        },
        "lifetime": {
          "oneOf": [
            {
              "enum": [
                "persistent",
                "frame",
                "transient",
                "history",
                "external"
              ]
            },
            {
              "$ref": "#/$defs/historyLifetime"
            }
          ]
        },
        "usage": {
          "enum": [
            "staticDraw",
            "dynamicDraw",
            "streamDraw"
          ]
        }
      },
      "required": [
        "id",
        "kind",
        "lifetime"
      ],
      "type": "object"
    }
  ]
}

content · v5 ​

字段 / 分支本对象必需性结构约束
oneOf[1].typerequiredconst="undefined"
oneOf[2].typerequiredconst="external"
oneOf[3].typerequiredconst="clear"
oneOf[3].valuerequiredoneOf: 2
oneOf[4].encodingoptional hereenum=["image","raw"]
oneOf[4].facesoptional heretype="object"; additionalProperties=false
oneOf[4].faces.negativeXrequired$ref="#/$defs/relativePath"
oneOf[4].faces.negativeYrequired$ref="#/$defs/relativePath"
oneOf[4].faces.negativeZrequired$ref="#/$defs/relativePath"
oneOf[4].faces.positiveXrequired$ref="#/$defs/relativePath"
oneOf[4].faces.positiveYrequired$ref="#/$defs/relativePath"
oneOf[4].faces.positiveZrequired$ref="#/$defs/relativePath"
oneOf[4].pathoptional here$ref="#/$defs/relativePath"
oneOf[4].typerequiredconst="asset"
oneOf[5].generatorrequired$ref="#/$defs/identifier"
oneOf[5].typerequiredconst="generated"
oneOf[5].versionrequired$ref="#/$defs/positiveVersion"
oneOf[6].servicerequired$ref="#/$defs/identifier"
oneOf[6].typerequiredconst="service"
oneOf[6].versionrequired$ref="#/$defs/positiveVersion"
oneOf[7].typerequiredconst="materialTable"
oneOf[7].versionrequiredconst=1
完整结构规则: #/$defs/content
json
{
  "oneOf": [
    {
      "enum": [
        "undefined",
        "external"
      ]
    },
    {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "undefined"
        }
      },
      "required": [
        "type"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "external"
        }
      },
      "required": [
        "type"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "clear"
        },
        "value": {
          "oneOf": [
            {
              "items": {
                "type": "number"
              },
              "maxItems": 1,
              "minItems": 1,
              "type": "array"
            },
            {
              "items": {
                "type": "number"
              },
              "maxItems": 4,
              "minItems": 4,
              "type": "array"
            }
          ]
        }
      },
      "required": [
        "type",
        "value"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "allOf": [
        {
          "oneOf": [
            {
              "required": [
                "path"
              ]
            },
            {
              "required": [
                "faces"
              ]
            }
          ]
        }
      ],
      "properties": {
        "encoding": {
          "enum": [
            "image",
            "raw"
          ]
        },
        "faces": {
          "additionalProperties": false,
          "properties": {
            "negativeX": {
              "$ref": "#/$defs/relativePath"
            },
            "negativeY": {
              "$ref": "#/$defs/relativePath"
            },
            "negativeZ": {
              "$ref": "#/$defs/relativePath"
            },
            "positiveX": {
              "$ref": "#/$defs/relativePath"
            },
            "positiveY": {
              "$ref": "#/$defs/relativePath"
            },
            "positiveZ": {
              "$ref": "#/$defs/relativePath"
            }
          },
          "required": [
            "positiveX",
            "negativeX",
            "positiveY",
            "negativeY",
            "positiveZ",
            "negativeZ"
          ],
          "type": "object"
        },
        "path": {
          "$ref": "#/$defs/relativePath"
        },
        "type": {
          "const": "asset"
        }
      },
      "required": [
        "type"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "generator": {
          "$ref": "#/$defs/identifier"
        },
        "type": {
          "const": "generated"
        },
        "version": {
          "$ref": "#/$defs/positiveVersion"
        }
      },
      "required": [
        "type",
        "generator",
        "version"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "service": {
          "$ref": "#/$defs/identifier"
        },
        "type": {
          "const": "service"
        },
        "version": {
          "$ref": "#/$defs/positiveVersion"
        }
      },
      "required": [
        "type",
        "service",
        "version"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "materialTable"
        },
        "version": {
          "const": 1
        }
      },
      "required": [
        "type",
        "version"
      ],
      "type": "object"
    }
  ]
}

size · v5 ​

字段 / 分支本对象必需性结构约束
heightoptional heretype="integer"; minimum=1
moderequiredenum=["absolute","viewport","output"]
scaleoptional heretype="array"; minItems=2; maxItems=2
widthoptional heretype="integer"; minimum=1
完整结构规则: #/$defs/size
json
{
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "mode": {
            "const": "absolute"
          }
        },
        "required": [
          "mode"
        ]
      },
      "then": {
        "allOf": [
          {
            "not": {
              "anyOf": [
                {
                  "required": [
                    "scale"
                  ]
                }
              ]
            }
          }
        ],
        "required": [
          "width",
          "height"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "mode": {
            "enum": [
              "viewport",
              "output"
            ]
          }
        }
      },
      "then": {
        "not": {
          "anyOf": [
            {
              "required": [
                "width"
              ]
            },
            {
              "required": [
                "height"
              ]
            }
          ]
        }
      }
    }
  ],
  "properties": {
    "height": {
      "minimum": 1,
      "type": "integer"
    },
    "mode": {
      "enum": [
        "absolute",
        "viewport",
        "output"
      ]
    },
    "scale": {
      "items": {
        "exclusiveMinimum": 0,
        "type": "number"
      },
      "maxItems": 2,
      "minItems": 2,
      "type": "array"
    },
    "width": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "mode"
  ],
  "type": "object"
}

sampling · v5 ​

字段 / 分支本对象必需性结构约束
magFilteroptional hereenum=["nearest","linear"]
minFilteroptional hereenum=["nearest","linear"]
mipLevelsoptional heretype="integer"; minimum=1
wrapSoptional hereenum=["repeat","clampToEdge","mirroredRepeat"]
wrapToptional hereenum=["repeat","clampToEdge","mirroredRepeat"]
完整结构规则: #/$defs/sampling
json
{
  "additionalProperties": false,
  "properties": {
    "magFilter": {
      "enum": [
        "nearest",
        "linear"
      ]
    },
    "minFilter": {
      "enum": [
        "nearest",
        "linear"
      ]
    },
    "mipLevels": {
      "minimum": 1,
      "type": "integer"
    },
    "wrapS": {
      "enum": [
        "repeat",
        "clampToEdge",
        "mirroredRepeat"
      ]
    },
    "wrapT": {
      "enum": [
        "repeat",
        "clampToEdge",
        "mirroredRepeat"
      ]
    }
  },
  "type": "object"
}

historyLifetime · v5 ​

字段 / 分支本对象必需性结构约束
capacityrequiredtype="integer"; minimum=2
kindrequiredconst="history"
完整结构规则: #/$defs/historyLifetime
json
{
  "additionalProperties": false,
  "properties": {
    "capacity": {
      "minimum": 2,
      "type": "integer"
    },
    "kind": {
      "const": "history"
    }
  },
  "required": [
    "kind",
    "capacity"
  ],
  "type": "object"
}

resourceView · v5 ​

字段 / 分支本对象必需性结构约束
framesAgooptional heretype="integer"; minimum=1
resourcerequired$ref="#/$defs/identifier"
viewoptional hereenum=["dawnlight:direct","dawnlight:history/current","dawnlight:history/previous","dawnlight:shadow/consumer","dawnlight:shadow/producer"]
完整结构规则: #/$defs/resourceView
json
{
  "additionalProperties": false,
  "allOf": [
    {
      "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"
              ]
            }
          ]
        }
      }
    }
  ],
  "properties": {
    "framesAgo": {
      "minimum": 1,
      "type": "integer"
    },
    "resource": {
      "$ref": "#/$defs/identifier"
    },
    "view": {
      "enum": [
        "dawnlight:direct",
        "dawnlight:history/current",
        "dawnlight:history/previous",
        "dawnlight:shadow/consumer",
        "dawnlight:shadow/producer"
      ]
    }
  },
  "required": [
    "resource"
  ],
  "type": "object"
}

完整示例 ​

来源与机器记录 ​

字段归属清单 · Schema v5 · Catalog v2 · Completion v2

schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·

ShaderPackManifestLoader.cs

作者文档 · Manifest v5 / Scene ABI v2