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].content | optional here | $ref="#/$defs/content" |
oneOf[0].format | optional here | $ref="#/$defs/nonEmptyString" |
oneOf[0].historyCapacity | optional here | type="integer"; minimum=2 |
oneOf[0].id | required | $ref="#/$defs/identifier" |
oneOf[0].kind | required | enum=["texture2D","textureCube"] |
oneOf[0].lifetime | required | oneOf: 2 |
oneOf[0].sampling | optional here | $ref="#/$defs/sampling" |
oneOf[0].size | optional here | $ref="#/$defs/size" |
oneOf[1].byteSize | optional here | type="integer"; minimum=1 |
oneOf[1].content | optional here | $ref="#/$defs/content" |
oneOf[1].id | required | $ref="#/$defs/identifier" |
oneOf[1].kind | required | const="buffer" |
oneOf[1].lifetime | required | oneOf: 2 |
oneOf[1].usage | optional here | enum=["staticDraw","dynamicDraw","streamDraw"] |
完整结构规则: #/$defs/resource
{
"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].type | required | const="undefined" |
oneOf[2].type | required | const="external" |
oneOf[3].type | required | const="clear" |
oneOf[3].value | required | oneOf: 2 |
oneOf[4].encoding | optional here | enum=["image","raw"] |
oneOf[4].faces | optional here | type="object"; additionalProperties=false |
oneOf[4].faces.negativeX | required | $ref="#/$defs/relativePath" |
oneOf[4].faces.negativeY | required | $ref="#/$defs/relativePath" |
oneOf[4].faces.negativeZ | required | $ref="#/$defs/relativePath" |
oneOf[4].faces.positiveX | required | $ref="#/$defs/relativePath" |
oneOf[4].faces.positiveY | required | $ref="#/$defs/relativePath" |
oneOf[4].faces.positiveZ | required | $ref="#/$defs/relativePath" |
oneOf[4].path | optional here | $ref="#/$defs/relativePath" |
oneOf[4].type | required | const="asset" |
oneOf[5].generator | required | $ref="#/$defs/identifier" |
oneOf[5].type | required | const="generated" |
oneOf[5].version | required | $ref="#/$defs/positiveVersion" |
oneOf[6].service | required | $ref="#/$defs/identifier" |
oneOf[6].type | required | const="service" |
oneOf[6].version | required | $ref="#/$defs/positiveVersion" |
oneOf[7].type | required | const="materialTable" |
oneOf[7].version | required | const=1 |
完整结构规则: #/$defs/content
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
height | optional here | type="integer"; minimum=1 |
mode | required | enum=["absolute","viewport","output"] |
scale | optional here | type="array"; minItems=2; maxItems=2 |
width | optional here | type="integer"; minimum=1 |
完整结构规则: #/$defs/size
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
magFilter | optional here | enum=["nearest","linear"] |
minFilter | optional here | enum=["nearest","linear"] |
mipLevels | optional here | type="integer"; minimum=1 |
wrapS | optional here | enum=["repeat","clampToEdge","mirroredRepeat"] |
wrapT | optional here | enum=["repeat","clampToEdge","mirroredRepeat"] |
完整结构规则: #/$defs/sampling
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
capacity | required | type="integer"; minimum=2 |
kind | required | const="history" |
完整结构规则: #/$defs/historyLifetime
{
"additionalProperties": false,
"properties": {
"capacity": {
"minimum": 2,
"type": "integer"
},
"kind": {
"const": "history"
}
},
"required": [
"kind",
"capacity"
],
"type": "object"
}resourceView · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
framesAgo | optional here | type="integer"; minimum=1 |
resource | required | $ref="#/$defs/identifier" |
view | optional here | enum=["dawnlight:direct","dawnlight:history/current","dawnlight:history/previous","dawnlight:shadow/consumer","dawnlight:shadow/producer"] |
完整结构规则: #/$defs/resourceView
{
"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 ·