七种 Command
行为与约束
以下词表属于 command_list@1;命令按数组顺序执行。完整结构包含各 type 的条件 required/forbidden 字段,不能把通用 command 对象的全部可选字段同时填入每种命令。
| type | Program 与关键行为 |
|---|---|
| fullscreen | 必需 graphics Program;绘制到 named targets |
| present | 必需 graphics Program;输出到默认 framebuffer,不用它冒充任意 MRT 写入 |
| compute | 必需 compute Program;dispatch.groups 为三维工作组数,barriers 是声明的 memory barrier 集合 |
| engineDraw | provider/id/version 调用可信宿主绘制;Program 可选,Scene 路径还受 sceneProvider 与类别合同约束 |
| copy | 禁止 Program;source/destination、aspects、filter、restore 表达 framebuffer transfer |
| clear | 禁止 Program;对命名目标或适用默认 framebuffer 清理;附件格式必须匹配 clear 值 |
| historyCommit | 禁止 Program;resource 必须是 history,标记当前帧完成,不是假造资源读写 |
copy 首版只接受一个 direct texture2D color 或 depth aspect,源/目标格式完全一致;深度只用 nearest,不支持 history view、stencil 或 combined aspects。每条 history 每帧最多 commit 一次,必须存在同帧 writer,所有 writer 在 commit 前有序;无 writer、重复、后置/无序 writer 都应拒绝。
engineDraw 使用 graphics Program 时,Program、bindings/semantics/targets/state 属于调用描述,Provider 保留可信几何提交与动态输入。BuiltIn fallback 是声明式 recipe:不能向它塞入包自有 Program、bindings、semantics 或 drawBuffers。viewport 的 source/restore/synchronizeScissor 和 state 恢复也属于实际执行边界,失败不能留下半套 GL 状态。
自动生成的 v5 结构
必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。
command · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
bindings | optional here | type="array"; items=#/$defs/binding |
clear | optional here | $ref="#/$defs/clear" |
copy | optional here | $ref="#/$defs/copy" |
customBindings | optional here | type="array"; maxItems=128; items=#/$defs/customBinding |
dispatch | optional here | $ref="#/$defs/dispatch" |
drawBuffers | optional here | $ref="#/$defs/drawBufferLayout" |
program | optional here | $ref="#/$defs/identifier" |
provider | optional here | $ref="#/$defs/provider" |
resource | optional here | $ref="#/$defs/identifier" |
sceneBindings | optional here | type="array"; items=#/$defs/sceneBinding |
sceneProvider | optional here | $ref="#/$defs/provider" |
semantics | optional here | type="array"; items=#/$defs/semantic |
state | optional here | $ref="#/$defs/state" |
targets | optional here | $ref="#/$defs/targets" |
type | required | enum=["fullscreen","compute","copy","clear","present","engineDraw","historyCommit"] |
viewport | optional here | $ref="#/$defs/viewport" |
完整结构规则: #/$defs/command
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "fullscreen"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"program",
"targets"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "compute"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"program",
"dispatch"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "copy"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"copy"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "clear"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"clear"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "present"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"program"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "historyCommit"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"resource"
]
}
},
{
"if": {
"not": {
"properties": {
"type": {
"const": "copy"
}
},
"required": [
"type"
]
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"copy"
]
}
]
}
}
},
{
"if": {
"not": {
"properties": {
"type": {
"const": "historyCommit"
}
},
"required": [
"type"
]
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"resource"
]
}
]
}
}
},
{
"if": {
"properties": {
"type": {
"const": "compute"
}
},
"required": [
"type"
]
},
"then": {
"not": {
"anyOf": [
{
"required": [
"viewport"
]
},
{
"required": [
"clear"
]
},
{
"required": [
"targets"
]
},
{
"required": [
"state"
]
}
]
}
}
},
{
"if": {
"properties": {
"type": {
"const": "present"
}
},
"required": [
"type"
]
},
"then": {
"not": {
"anyOf": [
{
"required": [
"targets"
]
},
{
"required": [
"drawBuffers"
]
}
]
}
}
},
{
"if": {
"properties": {
"type": {
"const": "copy"
}
},
"required": [
"type"
]
},
"then": {
"not": {
"anyOf": [
{
"required": [
"program"
]
},
{
"required": [
"bindings"
]
},
{
"required": [
"semantics"
]
},
{
"required": [
"sceneBindings"
]
},
{
"required": [
"targets"
]
},
{
"required": [
"drawBuffers"
]
},
{
"required": [
"state"
]
},
{
"required": [
"viewport"
]
},
{
"required": [
"clear"
]
},
{
"required": [
"dispatch"
]
}
]
}
}
},
{
"if": {
"properties": {
"type": {
"const": "clear"
}
},
"required": [
"type"
]
},
"then": {
"not": {
"anyOf": [
{
"required": [
"drawBuffers"
]
}
]
}
}
},
{
"if": {
"properties": {
"type": {
"const": "historyCommit"
}
},
"required": [
"type"
]
},
"then": {
"not": {
"anyOf": [
{
"required": [
"program"
]
},
{
"required": [
"bindings"
]
},
{
"required": [
"semantics"
]
},
{
"required": [
"sceneBindings"
]
},
{
"required": [
"targets"
]
},
{
"required": [
"drawBuffers"
]
},
{
"required": [
"state"
]
},
{
"required": [
"viewport"
]
},
{
"required": [
"clear"
]
},
{
"required": [
"dispatch"
]
},
{
"required": [
"copy"
]
}
]
}
}
},
{
"if": {
"properties": {
"type": {
"const": "engineDraw"
}
},
"required": [
"type"
]
},
"then": {
"oneOf": [
{
"required": [
"provider"
]
},
{
"required": [
"sceneProvider"
]
}
]
}
},
{
"if": {
"not": {
"properties": {
"type": {
"const": "engineDraw"
}
},
"required": [
"type"
]
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"provider"
]
},
{
"required": [
"sceneProvider"
]
}
]
}
}
},
{
"if": {
"properties": {
"type": {
"enum": [
"copy",
"clear",
"historyCommit"
]
}
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"customBindings"
]
}
]
}
}
},
{
"if": {
"allOf": [
{
"required": [
"customBindings"
]
}
],
"properties": {
"type": {
"const": "engineDraw"
}
},
"required": [
"type"
]
},
"then": {
"allOf": [
{
"not": {
"anyOf": [
{
"required": [
"provider"
]
}
]
}
}
],
"required": [
"program",
"sceneProvider"
]
}
}
],
"properties": {
"bindings": {
"items": {
"$ref": "#/$defs/binding"
},
"type": "array"
},
"clear": {
"$ref": "#/$defs/clear"
},
"copy": {
"$ref": "#/$defs/copy"
},
"customBindings": {
"items": {
"$ref": "#/$defs/customBinding"
},
"maxItems": 128,
"type": "array"
},
"dispatch": {
"$ref": "#/$defs/dispatch"
},
"drawBuffers": {
"$ref": "#/$defs/drawBufferLayout"
},
"program": {
"$ref": "#/$defs/identifier"
},
"provider": {
"$ref": "#/$defs/provider"
},
"resource": {
"$ref": "#/$defs/identifier"
},
"sceneBindings": {
"items": {
"$ref": "#/$defs/sceneBinding"
},
"type": "array"
},
"sceneProvider": {
"$ref": "#/$defs/provider"
},
"semantics": {
"items": {
"$ref": "#/$defs/semantic"
},
"type": "array"
},
"state": {
"$ref": "#/$defs/state"
},
"targets": {
"$ref": "#/$defs/targets"
},
"type": {
"enum": [
"fullscreen",
"compute",
"copy",
"clear",
"present",
"engineDraw",
"historyCommit"
]
},
"viewport": {
"$ref": "#/$defs/viewport"
}
},
"required": [
"type"
],
"type": "object"
}copy · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
aspects | required | type="array"; minItems=1; uniqueItems=true |
destination | required | oneOf: 2 |
filter | optional here | enum=["nearest","linear"] |
restore | optional here | enum=["none","frame"] |
source | required | oneOf: 2 |
完整结构规则: #/$defs/copy
{
"additionalProperties": false,
"properties": {
"aspects": {
"items": {
"enum": [
"color",
"depth"
]
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
"destination": {
"oneOf": [
{
"$ref": "#/$defs/identifier"
},
{
"$ref": "#/$defs/resourceView"
}
]
},
"filter": {
"enum": [
"nearest",
"linear"
]
},
"restore": {
"enum": [
"none",
"frame"
]
},
"source": {
"oneOf": [
{
"$ref": "#/$defs/identifier"
},
{
"$ref": "#/$defs/resourceView"
}
]
}
},
"required": [
"source",
"destination",
"aspects"
],
"type": "object"
}clear · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
color | optional here | type="array"; minItems=4; maxItems=4 |
depth | optional here | type="number"; minimum=0; maximum=1 |
stencil | optional here | type="integer"; minimum=0 |
完整结构规则: #/$defs/clear
{
"additionalProperties": false,
"minProperties": 1,
"properties": {
"color": {
"items": {
"type": "number"
},
"maxItems": 4,
"minItems": 4,
"type": "array"
},
"depth": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"stencil": {
"minimum": 0,
"type": "integer"
}
},
"type": "object"
}dispatch · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
barriers | optional here | type="array"; uniqueItems=true |
groups | required | type="array"; minItems=3; maxItems=3 |
完整结构规则: #/$defs/dispatch
{
"additionalProperties": false,
"properties": {
"barriers": {
"items": {
"enum": [
"shaderImageAccess",
"textureFetch",
"textureUpdate",
"shaderStorage",
"bufferUpdate",
"framebuffer"
]
},
"type": "array",
"uniqueItems": true
},
"groups": {
"items": {
"minimum": 1,
"type": "integer"
},
"maxItems": 3,
"minItems": 3,
"type": "array"
}
},
"required": [
"groups"
],
"type": "object"
}viewport · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
restore | required | enum=["none","frame"] |
source | required | enum=["target","frame"] |
synchronizeScissor | optional here | type="boolean" |
完整结构规则: #/$defs/viewport
{
"additionalProperties": false,
"properties": {
"restore": {
"enum": [
"none",
"frame"
]
},
"source": {
"enum": [
"target",
"frame"
]
},
"synchronizeScissor": {
"type": "boolean"
}
},
"required": [
"source",
"restore"
],
"type": "object"
}provider · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
id | required | $ref="#/$defs/identifier" |
version | required | $ref="#/$defs/positiveVersion" |
完整结构规则: #/$defs/provider
{
"additionalProperties": false,
"properties": {
"id": {
"$ref": "#/$defs/identifier"
},
"version": {
"$ref": "#/$defs/positiveVersion"
}
},
"required": [
"id",
"version"
],
"type": "object"
}完整示例
来源与机器记录
字段归属清单 · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·