GPUQueue: writeBuffer() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("WebGPU API")}}{{SecureContext_Header}}{{AvailableInWorkers}}
The **writeBuffer()** method of the {{domxref("GPUQueue")}} interface writes a provided data source into a given {{domxref("GPUBuffer")}}.
This is a convenience function, which provides an alternative to setting buffer data via buffer mapping and buffer-to-buffer copies. It lets the user agent determine the most efficient way to copy the data over.
Syntax
writeBuffer(buffer, bufferOffset, data, dataOffset, size)Parameters
buffer- : A {{domxref("GPUBuffer")}} object representing the buffer to write data to.
bufferOffset- : A number representing the offset, in bytes, to start writing the data at inside the {{domxref("GPUBuffer")}}.
data- : An object representing the data source to write into the {{domxref("GPUBuffer")}}. This can be an {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}}.
dataOffset{{optional_inline}}- : A number representing the offset to start writing the data from inside the data source. This value is a number of elements if
datais a {{jsxref("TypedArray")}}, and a number of bytes if not. If omitted,dataOffsetdefaults to 0. size{{optional_inline}}- : A number representing the size of the content to write from
datatobuffer. This value is a number of elements ifdatais a {{jsxref("TypedArray")}}, and a number of bytes if not. If omitted,sizewill be equal to the overall size ofdata, minusdataOffset.
Return value
None ({{jsxref("undefined")}}).
Exceptions
OperationError{{domxref("DOMException")}}- : The method throws an
OperationErrorif the following criteria are not met: - The size of
datais equal to or greater than 0. dataOffsetis equal to or smaller than the size ofdata.- The size of
data(when converted to bytes, in the case ofTypedArrays) is a multiple of 4.
Validation
The following criteria must be met when calling **writeBuffer()**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUQueue")}} becomes invalid:
bufferis available for use, i.e., not unavailable (GPUBuffers are unavailable if they are currently {{domxref("GPUBuffer.mapAsync", "mapped", "", "nocode")}}) or destroyed (with the {{domxref("GPUBuffer.destroy()")}} method).- The
buffer's {{domxref("GPUBuffer.usage")}} includes theGPUBufferUsage.COPY_DSTflag. bufferOffset, when converted to bytes, is a multiple of 4.- The size of
data-dataOffset+bufferOffset, when converted to bytes, is equal to or less than thebuffer's {{domxref("GPUBuffer.size")}}.
Examples
In our basic render demo, we define some vertex data in a {{jsxref("Float32Array")}} that we'll use to draw a triangle:
const vertices = new Float32Array([
0.0, 0.6, 0, 1, 1, 0, 0, 1, -0.5, -0.6, 0, 1, 0, 1, 0, 1, 0.5, -0.6, 0, 1, 0,
0, 1, 1,
]);To use this data in a render pipeline, we need to put it into a {{domxref("GPUBuffer")}}. First we'll create the buffer:
const vertexBuffer = device.createBuffer({
size: vertices.byteLength, // make it big enough to store vertices in
usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
});To get the data into the buffer we can use writeBuffer():
device.queue.writeBuffer(vertexBuffer, 0, vertices, 0, vertices.length);Specifications
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- The WebGPU API