diff --git a/spec/index.bs b/spec/index.bs index fed1f2132f..de2a24584e 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -2391,6 +2391,13 @@ interface GPUCommandEncoder { GPUTextureCopyView destination, GPUExtent3D copySize); + void inlineUpdateBuffer( + ArrayBuffer source, + GPUSize64 sourceOffset, + GPUBuffer destination, + GPUSize64 destinationOffset, + GPUSize64 size); + void pushDebugGroup(DOMString groupLabel); void popDebugGroup(); void insertDebugMarker(DOMString markerLabel); @@ -2517,6 +2524,52 @@ dictionary GPUImageBitmapCopyView { +### inlineUpdateBuffer(source, sourceOffset, destination, destinationOffset, size) ### {#GPUCommandEncoder-inlineUpdateBuffer} + +It's often useful for applications to update buffer data prior to draw or compute operations. +For example, updating model-view and projection matrices before or interleaved with rendering of a scene. +When these uploads are small, it's viable to inline the update data into the command buffer. +This does require more copies than other upload paths, but for small data sizes this overhead is negligible. +Implementations are expected to warn against using this for medium-to-large buffer updates. (e.g. >64k) + +In Vulkan, this is similar to |vkCmdUpdateBuffer|. +In D3D12, implementations can leverage |ID3D12GraphicsCommandList2::WriteBufferImmediate|. +Metal might use |makeBuffer(bytesNoCopy:length:options:deallocator:)| around some section of shared command buffer serialization memory. + +
+ + **Arguments:** + - {{ArrayBuffer}} |source| + - {{GPUSize64}} |sourceOffset| + - {{GPUBuffer}} |destination| + - {{GPUSize64}} |destinationOffset| + - {{GPUSize64}} |size| + + **Returns:** void + + Embed a copy of |source| from |sourceOffset| to |size| into the {{GPUCommandEncoder}}. + Encode a command into the {{GPUCommandEncoder}} that copies |size| bytes of data from embedded copy to the |destinationOffset| of another {{GPUBuffer}} |destination|. + +
+ Valid Usage + + Given a {{GPUCommandEncoder}} |encoder| and the arguments {{ArrayBuffer}} |source|, {{GPUSize64}} |sourceOffset|, {{GPUBuffer}} |destination|, {{GPUSize64}} |destinationOffset|, {{GPUSize64}} |size|, the following validation rules apply: + + - |encoder| must be a [=valid=] {{GPUCommandEncoder}}. + - |encoder|.{{GPUCommandEncoder/inlineUpdateBuffer()}} must not be called when a {{GPURenderPassEncoder}} is active on |encoder|. + - |encoder|.{{GPUCommandEncoder/inlineUpdateBuffer()}} must not be called when a {{GPUComputePassEncoder}} is active on |encoder|. + - |destination| must be a [=valid=] {{GPUBuffer}}. + - The {{GPUBuffer/[[usage]]}} of |destination| must contain {{GPUBufferUsage/COPY_DST}}. + - |size| must be a multiple of 4. + - |sourceOffset| must be a multiple of 4. + - |destinationOffset| must be a multiple of 4. + - (|sourceOffset| + |size|) must not overflow a {{GPUSize64}}. + - (|destinationOffset| + |size|) must not overflow a {{GPUSize64}}. + - The {{ArrayBuffer/byteLength}} of |source| must be greater than or equal to (|sourceOffset| + |size|). + - The {{GPUBuffer/[[size]]}} of |destination| must be greater than or equal to (|destinationOffset| + |size|). +
+
+ ## Programmable Passes ## {#programmable-passes}