GPUBuffer: mapAsync() 方法

实验性： 这是一个 实验性技术
在生产环境中使用此功能前，请仔细查看 浏览器兼容性表。

安全上下文： 此功能仅在 安全上下文（HTTPS）中可用，在某些或所有 支持的浏览器 中。

mapAsync() 方法是 GPUBuffer 接口的方法，用于映射指定的 GPUBuffer 范围。它返回一个 Promise，该 Promise 在 GPUBuffer 的内容准备好访问时解析。当 GPUBuffer 被映射时，它不能用于任何 GPU 命令。

一旦缓冲区成功映射（可以通过 GPUBuffer.mapState 检查），对 GPUBuffer.getMappedRange() 的调用将返回一个 ArrayBuffer，其中包含 GPUBuffer 的当前值，以便根据需要由 JavaScript 读取和更新。

完成对 GPUBuffer 值的操作后，请调用 GPUBuffer.unmap() 以取消映射它，使其再次可供 GPU 访问。

语法

js
mapAsync(mode)
mapAsync(mode, offset, size)

参数

mode

一个 按位标志，用于指定 GPUBuffer 是为读取还是写入而映射。可能的值为

GPUMapMode.READ

GPUBuffer 被映射为读取模式。可以读取值，但对 ArrayBuffer（由 GPUBuffer.getMappedRange() 返回）所做的任何更改，一旦调用 GPUBuffer.unmap() 就会被丢弃。

读取模式映射只能用于在其使用属性中设置了 GPUBufferUsage.MAP_READ 的 GPUBuffer（即，使用 GPUDevice.createBuffer() 创建时）。

GPUMapMode.WRITE

GPUBuffer 被映射为写入模式。可以读取和更新值——对 ArrayBuffer（由 GPUBuffer.getMappedRange() 返回）所做的任何更改，一旦调用 GPUBuffer.unmap() 就会保存到 GPUBuffer 中。

写入模式映射只能用于在其使用属性中设置了 GPUBufferUsage.MAP_WRITE 的 GPUBuffer（即，使用 GPUDevice.createBuffer() 创建时）。

offset 可选

表示从缓冲区开始位置到要映射范围开始位置的偏移量（以字节为单位）的数字。如果省略 offset，则默认为 0。

size 可选

表示要映射范围的大小（以字节为单位）的数字。如果省略 size，则映射的范围扩展到 GPUBuffer 的末尾。

返回值

一个 Promise，当 GPUBuffer 的内容准备好被访问时，它会解析为 Undefined。

验证

调用 mapSync() 时必须满足以下条件，否则会抛出 OperationError DOMException，promise 被拒绝，并生成 GPUValidationError

  • offset 是 8 的倍数。
  • 要映射的总范围（如果指定了 size，则为 size；否则为 GPUBuffer.size - offset）是 4 的倍数。
  • 要映射的总范围在 GPUBuffer 的边界内。
  • 如果 mode 为 GPUMapMode.READ，则 GPUBuffer 的使用属性为 GPUBufferUsage.MAP_READ。
  • 如果 mode 为 GPUMapMode.WRITE，则 GPUBuffer 的使用属性为 GPUBufferUsage.MAP_WRITE。

示例

有关示例，请参阅 主要 GPUBuffer 页面。

规范

规范
WebGPU
# dom-gpubuffer-mapasync

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅