diff --git a/spec/index.bs b/spec/index.bs index dc522d683e..16a4a1a461 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -1316,6 +1316,42 @@ Issue: Add client-side validation that a mapped buffer can only be unmapped and +## Buffer Uploads ## {#buffer-uploads} + +*This section is non-normative.* + +Modern graphics APIs have largely eschewed immediate data uploads in favor of mapping +host-visible buffers and enqueuing copies into other (especially device-local) buffers as needed. +Beginners in particular will want an easy way to upload new data for buffers without managing mappings. +We encourage use of helper functions (like below) until more sophisticated buffer and mapping management is required. +While copyDataToBuffer isn't always the most efficient approach, it is robust and easy to use for basic content. + +
+function copyDataToBuffer(device, queue, srcData, srcOffset, + dstBuffer, dstOffset, size) +{ + size = size || (srcData.byteLength - srcOffset); + + const [uploadBuf, map] = device.createBufferMapped({ + size: size, + usage: GPUBufferUsage.COPY_SRC, + }); + map.set(srcData, srcOffset); + uploadBuf.unmap(); + + const cenc = device.createCommandEncoder(); + cenc.copyBufferToBuffer(uploadBuf, 0, dstBuffer, dstOffset, size); + const cbuf = cenc.finish(); + + queue.submit([cbuf]); + uploadBuf.destroy(); +}; +
+ +More sophisticated content may require batched or pipelined uploads, possibly with staging areas and +other tuned heuristics. +Instead of guessing the intent of the application, this API offers the primitive building blocks to +construct efficient abstractions for any usecase. # Textures and Texture Views # {#textures}