changed 5 years ago
Linked with GitHub

Data upload API design rational

This document explains the design constraints for data upload to the GPU in WebGPU and documents all the different proposals that were surfaced to the group.

Aspects to consider

Because WebGPU is a Web API, and because of WebGPU's structure, the data upload design must:

  • not have blocking function calls
  • prevent races between Javascript and the GPU
  • be implementable for remoting implementations
  • gracefully handle device loss and error objects
  • work on multiple WebWorkers
  • for designs using an ArrayBuffer, detaching can only be done on the thread that created it

Other goals for the design that are more subjective to evaluate and in their importance:

  • reducing the number of copies necessary to get the data on the GPU in remoting implementations for both UMA and discrete devices
  • how easy it is to use the API in a performant and portable way ("pit of success")
  • how easy it is to understand for new graphics developers
  • how it maps to similar concepts in existing graphics APIs
  • how transparent the implementation and performance is

Buffer mapping proposals

Asynchronous mapping

Originally added in #147 (see also #49) and currently in the spec.

Missing in the spec is that a GPUBuffer can only be unmapped on the thread that mapped it.

Synchronous mapping with potential extra copies #506

Failable mapping #511

Buffer views in addition to asynchronous mapping #156

Removed because there's a number of bad interactions with the rest of the API, see #481. Noone has taken a shot at solving the interactions yet.

Immediate upload proposals

GPUQueue.writeToBuffer #509

At this point this design is clearly the preferred one out of all the immediate upload designs.

Note this is similar to the proposal in #154 and #418

GPUBuffer.setSubData #418

Also in #49.

Removed in favor of GPUQueue.writeToBuffer, because it makes the ordering of operations more clear.

GPUUploadPass #491

The semantics were complicated and the pass locked the queue, which made multithreaded scenarios challenging and added more API brittleness. Removed in favor of GPUQueue.writeToBuffer.

Buffered host access pass #45

Removed in favor of GPUQueue.writeToBuffer, requires storing the data in the command encoder which we'd like to avoid.

References

Meta discussion #138

Select a repo