跳转到正文

七种 Command ​

行为与约束 ​

以下词表属于 command_list@1;命令按数组顺序执行。完整结构包含各 type 的条件 required/forbidden 字段,不能把通用 command 对象的全部可选字段同时填入每种命令。

typeProgram 与关键行为
fullscreen必需 graphics Program;绘制到 named targets
present必需 graphics Program;输出到默认 framebuffer,不用它冒充任意 MRT 写入
compute必需 compute Program;dispatch.groups 为三维工作组数,barriers 是声明的 memory barrier 集合
engineDrawprovider/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 ​

字段 / 分支本对象必需性结构约束
bindingsoptional heretype="array"; items=#/$defs/binding
clearoptional here$ref="#/$defs/clear"
copyoptional here$ref="#/$defs/copy"
customBindingsoptional heretype="array"; maxItems=128; items=#/$defs/customBinding
dispatchoptional here$ref="#/$defs/dispatch"
drawBuffersoptional here$ref="#/$defs/drawBufferLayout"
programoptional here$ref="#/$defs/identifier"
provideroptional here$ref="#/$defs/provider"
resourceoptional here$ref="#/$defs/identifier"
sceneBindingsoptional heretype="array"; items=#/$defs/sceneBinding
sceneProvideroptional here$ref="#/$defs/provider"
semanticsoptional heretype="array"; items=#/$defs/semantic
stateoptional here$ref="#/$defs/state"
targetsoptional here$ref="#/$defs/targets"
typerequiredenum=["fullscreen","compute","copy","clear","present","engineDraw","historyCommit"]
viewportoptional here$ref="#/$defs/viewport"
完整结构规则: #/$defs/command
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
aspectsrequiredtype="array"; minItems=1; uniqueItems=true
destinationrequiredoneOf: 2
filteroptional hereenum=["nearest","linear"]
restoreoptional hereenum=["none","frame"]
sourcerequiredoneOf: 2
完整结构规则: #/$defs/copy
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
coloroptional heretype="array"; minItems=4; maxItems=4
depthoptional heretype="number"; minimum=0; maximum=1
stenciloptional heretype="integer"; minimum=0
完整结构规则: #/$defs/clear
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
barriersoptional heretype="array"; uniqueItems=true
groupsrequiredtype="array"; minItems=3; maxItems=3
完整结构规则: #/$defs/dispatch
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
restorerequiredenum=["none","frame"]
sourcerequiredenum=["target","frame"]
synchronizeScissoroptional heretype="boolean"
完整结构规则: #/$defs/viewport
json
{
  "additionalProperties": false,
  "properties": {
    "restore": {
      "enum": [
        "none",
        "frame"
      ]
    },
    "source": {
      "enum": [
        "target",
        "frame"
      ]
    },
    "synchronizeScissor": {
      "type": "boolean"
    }
  },
  "required": [
    "source",
    "restore"
  ],
  "type": "object"
}

provider · v5 ​

字段 / 分支本对象必需性结构约束
idrequired$ref="#/$defs/identifier"
versionrequired$ref="#/$defs/positiveVersion"
完整结构规则: #/$defs/provider
json
{
  "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 ·

ShaderPackManifestLoader.cs

作者文档 · Manifest v5 / Scene ABI v2