用途:面向 WebGPU 主机侧(host-side)内存对齐问题,帮助在调用 API 前就算出合规的缓冲区大小、拷贝偏移、bytesPerRow 和动态绑定组偏移,使首次调用即可通过校验。适用基线为 WebGPU 1.0-stable:Chrome 113+、Safari 26+、Firefox 141+。
主要能力与规则:WebGPU 在验证阶段拒绝一切未对齐的大小和偏移,不会静默取整,必须在主机侧先算好。常见约束包括:createBuffer 的 size(mappedAtCreation 时)为 4 的倍数;writeBuffer 的 bufferOffset 与写入 size 为 4 的倍数;mapAsync 的 offset 为 8 的倍数、size 为 4 的倍数;getMappedRange 的 offset 为 8 的倍数、size 为 4 的倍数;动态 uniform/storage 偏移为 minUniformBufferOffsetAlignment / minStorageBufferOffsetAlignment(256)的倍数;bytesPerRow 为 256 的倍数。这两个 256 是对齐下限类限制,适配器只会报告 256 或更高,不会更低;bytesPerRow 的 256 规则由规范固定,不随适配器变化。
必要用法:缓冲区到纹理拷贝的 bytesPerRow 用 Math.ceil(unpaddedBytesPerRow / 256) * 256 计算;回读缓冲区大小用 bytesPerRow * height,而非 width * height * 像素字节数;动态偏移步长用 Math.ceil(structByteSize / 256) * 256,例如 192 字节结构仍取 256 步长,setBindGroup 传 i * stride;writeBuffer 前把数据补齐到 4 字节边界。回读映射后仍需按行去掉填充字节,再 unmap,且 unmap 后不可再读取映射的 ArrayBuffer。
适用场景:WebGPU 中缓冲区大小计算、缓冲区与纹理互拷、动态绑定组偏移、映射回读等场景。
限制:本技能仅涉及主机侧对齐;WGSL 结构体字段布局(如 vec3 的 16 字节陷阱、@align、@size)属于 webgpu-wgsl-memory-layout。其余细节与代码示例见 references/methods.md、references/examples.md、references/anti-patterns.md。