WebGPU 动态更新 Storage Buffer 局部数据的三种高效方案

在 WebGPU 开发中，Storage Buffer（存储缓冲区）常用于存储海量的顶点、实例属性、物理粒子或渲染网格数据。当这些数据中只有一小部分发生动态变化（例如：仅更新某个粒子的位置，或者修改某个网格的变换矩阵）时，如果每次都将整块几十兆甚至上百兆的 Buffer 重新提交，会造成极大的 CPU-GPU 传输带宽浪费，甚至导致帧率断崖式下跌。

如何优雅、高效地实现 Storage Buffer 的局部更新？WebGPU 提供了几种不同维度的底层 API。本文将介绍三种主流的高效更新方案，并对比它们的适用场景与性能损耗。

方案一：最简直接法 —— device.queue.writeBuffer

对于大多数中轻量级的数据更新，最直接、最不容易出错的方法是使用 device.queue.writeBuffer。它允许你指定目标 Buffer 的偏移量（Offset）和数据长度，从而只覆盖特定区域。

代码实现

// 假设我们有一个容纳 1,000,000 个 float 数据的巨大 Storage Buffer
const storageBuffer = device.createBuffer({
  size: 1000000 * Float32Array.BYTES_PER_ELEMENT,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST, // 必须声明 COPY_DST
});

// 准备更新第 500 到第 510 个元素的数据
const subData = new Float32Array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]);

// 写入特定位置
const elementOffset = 500;
const byteOffset = elementOffset * Float32Array.BYTES_PER_ELEMENT;

device.queue.writeBuffer(
  storageBuffer,
  byteOffset, // 目标 Buffer 的字节偏移量
  subData.buffer, // 源数据 ArrayBuffer
  subData.byteOffset, // 源数据的字节偏移量
  subData.byteLength // 写入长度
);

运行机制与优缺点

• 机制：writeBuffer 是一个非阻塞的异步操作。浏览器内核会在后台自动分配一块临时内存（Staging Memory），将你的数据复制进去，然后在 GPU 的时间线上排队执行一次 GPU 内部的 Copy 操作。
• 优点：
  • API 极其简单，没有复杂的生命周期管理。
  • 不需要处理繁琐的 mapAsync 异步等待。
  • 适合更新频率低、数据量小的场景。
• 缺点：
  • 如果在一帧内频繁调用多次 writeBuffer（例如在一个循环里更新几百个零散的粒子），会产生大量的垃圾回收（GC）压力和内部微任务排队开销。
  • 多次小规模的 CPU-GPU 边界调用会积攒显著的 Context Switching 损耗。

方案二：显式 staging buffer + copyBufferToBuffer

如果你需要在一帧内合并多个零散的更新，或者需要精准控制内存分配，避免浏览器隐式创建临时内存，可以使用显式暂存缓冲区（Staging Buffer）。

其核心思想是：在 CPU 可写的 Staging Buffer 中写入数据，然后通过 GPUCommandEncoder.copyBufferToBuffer 一次性提交 GPU 级的数据拷贝。

代码实现

// 1. 创建大容量的 GPU 侧 Storage Buffer
const gpuStorageBuffer = device.createBuffer({
  size: 1000000 * 4,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
});

// 2. 创建一个较小的、CPU 可写的 Staging Buffer (必须具有 MAP_WRITE 和 COPY_SRC 标志)
const stagingBufferSize = 1024 * 4; // 假设单次更新最大不超过 4KB
const stagingBuffer = device.createBuffer({
  size: stagingBufferSize,
  usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC,
});

async function updateSubData(offsetInElements, dataArray) {
  const byteOffset = offsetInElements * Float32Array.BYTES_PER_ELEMENT;
  const byteLength = dataArray.byteLength;

  // 确保数据没有超出 Staging Buffer 限制
  if (byteLength > stagingBufferSize) {
    throw new Error("更新数据量超过了 Staging Buffer 的容量");
  }

  // 1. 将 Staging Buffer 映射到 CPU 内存空间
  await stagingBuffer.mapAsync(GPUMapMode.WRITE, 0, byteLength);
  
  // 2. 获取 CPU 侧的可写映射范围，并写入数据
  const mappedRange = stagingBuffer.getMappedRange(0, byteLength);
  new Float32Array(mappedRange).set(dataArray);
  
  // 3. 写入完毕后必须立刻解除映射，否则 GPU 无法访问
  stagingBuffer.unmap();

  // 4. 创建命令编码器，录制拷贝命令
  const commandEncoder = device.createCommandEncoder();
  commandEncoder.copyBufferToBuffer(
    stagingBuffer,   // 源 Buffer (Staging)
    0,               // 源 Buffer 偏移量
    gpuStorageBuffer, // 目标 Buffer (Storage)
    byteOffset,      // 目标 偏移量 (注意：必须是 4 的倍数)
    byteLength       // 拷贝字节长度 (注意：必须是 4 的倍数)
  );

  // 5. 提交执行
  device.queue.submit([commandEncoder.finish()]);
}

注意事项与对齐规则

WebGPU 规范对内存拷贝有着严格的对齐要求：

1. copyBufferToBuffer 中的 srcOffset、dstOffset 和 size 必须是 4 字节的倍数。如果你的数据类型是 Float32 或 Int32（每个占 4 字节），天然满足要求；如果是 Uint8 或 Uint16，则需要手动进行补齐计算。
2. 必须先执行 unmap()，然后才能将该 Buffer 放入 submit(...) 的命令流中，否则会触发 WebGPU 的 Validation Error。

方案三：高频高并发场景 —— 环形暂存池（Ring Staging Buffer Pool）

方案二虽然减少了隐式内存分配，但在高帧率（如 60FPS / 120FPS）的渲染循环中，await stagingBuffer.mapAsync 会带来致命的局限性：等待映射是异步的，如果在等待期间下一帧已经到来，就会产生严重的帧率抖动和 CPU 闲置。

为了彻底压榨 GPU 带宽，工业界通常采用 Ring Buffer (环形缓冲区) 或 Multi-buffering (多缓冲区) 机制。我们一次性创建多个 Staging Buffer 组成一个池子，轮流使用它们，从而消除等待 mapAsync 的阻塞时间。

环形缓冲池设计示意图

[ Frame N ]     -> 使用 StagingBuffer[0] 写入数据 -> 提交 Copy -> 渲染
[ Frame N+1 ]   -> 使用 StagingBuffer[1] 写入数据 -> 提交 Copy -> 渲染
[ Frame N+2 ]   -> 使用 StagingBuffer[2] 写入数据 -> 此时 [0] 早已空闲，将其 MapAsync 准备复用

代码架构实现

class StagingBufferPool {
  constructor(device, bufferSize, poolSize = 3) {
    this.device = device;
    this.bufferSize = bufferSize;
    this.poolSize = poolSize;
    this.buffers = [];
    this.activeIdx = 0;

    for (let i = 0; i < poolSize; i++) {
      this.buffers.push({
        buffer: device.createBuffer({
          size: bufferSize,
          usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC,
        }),
        isMapped: false,
        pendingMap: null
      });
    }
  }

  // 获取一个当前可用、且已经处于 Map 状态的 Buffer 包装对象
  async getAvailableBuffer() {
    const item = this.buffers[this.activeIdx];
    this.activeIdx = (this.activeIdx + 1) % this.poolSize;

    if (!item.isMapped) {
      if (item.pendingMap) {
        await item.pendingMap;
      } else {
        item.pendingMap = item.buffer.mapAsync(GPUMapMode.WRITE, 0, this.bufferSize);
        await item.pendingMap;
        item.pendingMap = null;
      }
      item.isMapped = true;
    }
    return item;
  }

  // 释放并归还，同时在后台重新触发 MapAsync 锁住它，供下几帧循环使用
  releaseAndMapBack(item) {
    item.buffer.unmap();
    item.isMapped = false;
    // 异步在后台开启下一次的 Map 操作，不需要在当前主线程渲染帧中 await 它
    item.pendingMap = item.buffer.mapAsync(GPUMapMode.WRITE, 0, this.bufferSize).then(() => {
      item.isMapped = true;
      item.pendingMap = null;
    });
  }
}

如何配合渲染循环使用？

const pool = new StagingBufferPool(device, 64 * 1024, 3); // 3 缓冲区设计

async function renderFrame() {
  // 1. 获取一个可用的暂存 Buffer（大概率已经预先 Map 好了，无需真正等待）
  const stagingItem = await pool.getAvailableBuffer();
  
  // 2. 写入你的动态局部数据
  const range = stagingItem.buffer.getMappedRange(0, 1024);
  const view = new Float32Array(range);
  view.set([/* 这一帧要更新的局部数据 */]);
  
  // 3. 归还并开启后台异步 Mapping
  pool.releaseAndMapBack(stagingItem);

  // 4. 提交 Copy 任务
  const commandEncoder = device.createCommandEncoder();
  commandEncoder.copyBufferToBuffer(stagingItem.buffer, 0, targetStorageBuffer, targetOffset, 1024);
  device.queue.submit([commandEncoder.finish()]);

  // 5. 执行后续渲染/计算 Pass...
  
  requestAnimationFrame(renderFrame);
}

三种方案的选型决策矩阵

最佳实践建议

1. 偶尔改一下配置参数、或者只在初始化/相机变动时更新数据：不要犹豫，直接用 device.queue.writeBuffer。这是最安全、最符合人体工程学的做法。
2. 每帧都有粒子消亡和诞生，需要更新局部连续内存：采用 显式 Staging Buffer + 拷贝。
3. 高画质游戏、大范围地形 LOD 动态加载、或者复杂的 WebGPU 物理模拟：必须构建 环形暂存池 (Ring Staging Pool)，利用多重缓冲掩盖 CPU 与 GPU 之间的握手延迟，从而实现真正的零卡顿局部数据更新。