WebGPU buffer mapAsync 怎样避免重复映射同一缓冲区

WebGPU 里，同一个 GPUBuffer 不能在一次映射尚未完成时再次调用 mapAsync()。最稳妥的做法不是每个读取请求都直接调用映射，而是把缓冲区当成一个小状态机：只有 mapState === "unmapped" 时发起新的映射；进入 pending 后复用正在进行的 Promise；进入 mapped 后读取并复制数据，最后调用 unmap() 把所有权交还给 GPU。

官方规范：https://gpuweb.github.io/gpuweb/

API 参考：https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/mapAsync

避免重复映射的关键是“一个 GPUBuffer 配一个正在进行的 map Promise”，而不是在调用方到处添加延时。重复调用只会把竞态变成映射失败，不能提高读取速度。

先看懂 mapState 的三个状态

GPUBuffer.mapState 只有三种常见状态：unmapped 表示当前没有映射，pending 表示 mapAsync() 已发出但还没完成，mapped 表示可以调用 getMappedRange() 取得 CPU 可访问的 ArrayBuffer。规范明确规定一个缓冲区不会同时存在两个 pending map，因此第二次映射请求应当被拒绝。

还要注意所有权变化：缓冲区处于 mapped 状态时不能提交使用它的 GPU 工作；读取或写入结束后必须 unmap()。unmap() 会让此前取得的映射数组失效，所以需要在 unmap 之前把数据复制到自己的 TypedArray。

创建缓冲区时先把读写方向定清楚

如果是把 GPU 计算结果读回 JavaScript，通常使用 GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST。如果是从 JavaScript 准备数据再复制到 GPU，则使用 GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC。读写标志不是可以随便混用的装饰，它决定了 mapAsync() 的 mode 是否有效。

const byteLength = 256;

const readbackBuffer = device.createBuffer({
  label: "readback-buffer",
  size: byteLength,
  // 读回 GPU 结果：允许复制进来，再以 MAP_READ 映射给 JavaScript。
  usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
});

const uploadBuffer = device.createBuffer({
  label: "upload-buffer",
  size: byteLength,
  // 上传 JavaScript 数据：CPU 写入后，以 COPY_SRC 复制到 GPU 资源。
  usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC,
});

mapAsync() 的范围也有硬约束：offset 必须是 8 的倍数，映射范围的 size 必须是 4 的倍数，并且范围不能越过缓冲区边界。示例里的 256 字节不是性能结论，只是同时满足这些对齐条件的易读值；真实项目仍应按实际数据长度向上对齐。

用单飞 Promise 合并重复读取

多个渲染帧、调试面板或业务回调可能会在很短时间内请求同一份 GPU 结果。让它们各自调用 mapAsync() 就会撞上 pending 状态。可以在缓冲区外维护一个 Promise：第一个调用负责发起映射，后续调用直接等待同一个 Promise。

const activeMaps = new WeakMap();

function readMappedBuffer(buffer, byteLength) {
  const active = activeMaps.get(buffer);
  if (active) {
    // 映射还在 pending 或读取收尾中，复用同一次请求，不再调用 mapAsync。
    return active;
  }

  if (buffer.mapState !== "unmapped") {
    // mapped 通常说明外部代码尚未 unmap，继续映射会掩盖所有权错误。
    return Promise.reject(new Error(`buffer 当前状态为 ${buffer.mapState}`));
  }

  const task = (async () => {
    try {
      // 等待映射完成后，才能安全取得 mapped range。
      await buffer.mapAsync(GPUMapMode.READ, 0, byteLength);
      const view = new Uint8Array(buffer.getMappedRange(0, byteLength));
      // unmap 会让 view 失效，先复制出独立的 JavaScript 数据。
      return view.slice();
    } finally {
      // 异常、取消或正常返回都要把缓冲区交还给 GPU。
      if (buffer.mapState === "mapped") buffer.unmap();
      activeMaps.delete(buffer);
    }
  })();

  activeMaps.set(buffer, task);
  return task;
}

// 两次调用共享一个映射过程，而不是向同一个 buffer 发出两次 mapAsync。
const firstRead = readMappedBuffer(readbackBuffer, byteLength);
const secondRead = readMappedBuffer(readbackBuffer, byteLength);
const [firstBytes, secondBytes] = await Promise.all([firstRead, secondRead]);

这里的“单飞”只合并同一个 GPUBuffer 的并发读取。若业务要读取不同的结果，应使用不同的 staging buffer 或等待前一次读取结束后再复用；不要用共享 Promise 把本来不同的数据请求错误地合并。

mapped 期间只读映射范围，复制后再 unmap

成功等待 mapAsync() 后，才可以调用 getMappedRange()。它的范围必须落在本次 mapAsync() 请求的范围内。对读映射来说，JavaScript 在映射数组上的修改不会在 unmap() 后写回 GPU；对写映射来说，写入内容则会在 unmap 时交还给 GPU。因此读回和上传应使用不同的代码路径，不能只替换一个 mode 字符串。

async function copyReadback(buffer, byteLength) {
  if (buffer.mapState !== "unmapped") {
    throw new Error(`开始读回前 buffer 状态不是 unmapped：${buffer.mapState}`);
  }

  try {
    // READ 模式必须与创建时的 MAP_READ 用法匹配。
    await buffer.mapAsync(GPUMapMode.READ, 0, byteLength);
    const mapped = buffer.getMappedRange(0, byteLength);
    // ArrayBuffer 会在 unmap 时失效，所以复制成独立副本再返回。
    return new Uint8Array(mapped).slice();
  } finally {
    // mapAsync 失败时可能仍是 unmapped；mapped 时才执行归还所有权。
    if (buffer.mapState === "mapped") buffer.unmap();
  }
}

不要把 getMappedRange() 返回的视图缓存到下一帧继续使用，也不要在 unmap() 后读取它。若需要异步交给别的模块，返回上面那样的副本，或者在更高层约定好数据所有权。

三种常见错误与对应修复

如果缓冲区只用于一次初始化，也可以在 createBuffer() 时使用 mappedAtCreation: true，写入后立刻 unmap()。这条路径不是对 pending 映射的替代品，而是创建阶段的同步填充方式；后续重复使用仍要遵守同一套所有权规则。

把规则收敛成一份调用清单

1. 同一 GPUBuffer 只允许一个活动的 mapAsync()；并发调用复用 Promise。
2. 调用前检查 mapState，不要把已经 mapped 的缓冲区再次映射。
3. READ/WRITE mode 必须与创建时的 MAP_READ/MAP_WRITE 用法匹配。
4. 检查 offset、size 对齐和边界，且 getMappedRange() 不能越出映射范围。
5. 在 mapped 期间完成读取或写入；需要跨越 unmap 保存的数据先复制。
6. 在 finally 中 unmap，并把活动 Promise 从表中删除，保证缓冲区可以复用。

所以，解决“重复映射同一缓冲区”的重点不是增加等待时间，而是给 GPUBuffer 建立明确的状态和所有权边界：pending 阶段只有一个请求，mapped 阶段只访问合法范围，收尾阶段一定 unmap。这个模式既能减少偶发映射错误，也能让读回路径在多处调用时保持可预测。

常见问题

可以在 mapAsync 尚未完成时调用 unmap 吗？

不建议把它当作取消机制。规范允许 unmap 终止 pending map 并使 Promise 以中止错误结束，但业务代码仍应让调用方知道这次读取没有完成，并清理自己的活动 Promise。

mapState 是 mapped 就一定可以提交 GPU 命令吗？

不可以。mapped 表示 CPU 可以访问映射范围，正因为 CPU 持有缓冲区，使用该缓冲区的 GPU 工作不能提交。先完成访问并调用 unmap，再提交相关命令。

为什么读回结果要调用 slice？

getMappedRange() 返回的 ArrayBuffer 属于当前映射，unmap 后会失效。slice 创建独立副本，允许业务逻辑在缓冲区重新交给 GPU 后继续处理数据。