Skip to content

Add the buffer mapping explainer #1600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kvark merged 4 commits into from
Apr 8, 2021
Merged

Add the buffer mapping explainer #1600

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1e812b8
Add the buffer mapping explainer
Kangz Apr 6, 2021
70c65be
explainer: use data-no-idl to prevent IDL parsing
kainino0x Apr 6, 2021
b66d756
use highlight=idl instead of class=idl to prevent generating idl index
kainino0x Apr 6, 2021
a335282
Address @kvark's comments
Kangz Apr 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Address @kvark's comments
  • Loading branch information
@Kangz
Kangz committed Apr 8, 2021
commit a3352824301949eafdd8c9c3773b2b49c62dc3cf
9 changes: 5 additions & 4 deletions explainer/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ This memory can be accessed linearly, contrary to `GPUTexture` for which the act

**CPU→GPU:** When using WebGPU, applications need to transfer data from JavaScript to `GPUBuffer` very often and potentially in large quantities.
This includes mesh data, drawing and computations parameters, ML model inputs, etc.
That's why an efficient way to update `GPUBuffer` data is needed. `GPUQueue.writeBuffer` is reasonably efficient but includes extra copies compared to the buffer mapping used for writing buffers.
That's why an efficient way to update `GPUBuffer` data is needed. `GPUQueue.writeBuffer` is reasonably efficient but includes at least an extra copy compared to the buffer mapping used for writing buffers.

**GPU→CPU:** Applications also often need to transfer data from the GPU to Javascript, though usually less often and in lesser quantities.
This includes screenshots, statistics from computations, simulation or ML model results, etc.
Expand Down Expand Up @@ -312,16 +312,17 @@ However it is valid (and encouraged!) to record `GPUCommandBuffer`s using the `G
### Creation of Mappable Buffers ### {#buffer-mapping-creation}

The physical memory location for a `GPUBuffer`'s underlying buffer depends on whether it should be mappable and whether it is mappable for reading or writing (native APIs give some control on the CPU cache behavior for example).
At the moment mappable buffers can only be used to transfer data (so they can only have the correct `COPY_SRC` or `COPY_DST` usage in addition to a `MAP_*` usage),
That's why applications must specify that buffers are mappable when they are created using the (currently) mutually exclusive `GPUBufferUsage.MAP_READ` and `GPUBufferUsage.MAP_WRITE` flags:

<div class=example>
<pre highlight="js">
const myMapReadBuffer = device.createBuffer({
usage: GPUBufferUsage.MAP_READ | otherUsages,
usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
size: 1000,
});
const myMapWriteBuffer = device.createBuffer({
usage: GPUBufferUsage.MAP_WRITE | otherUsages,
usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC,
size: 1000,
});
</pre>
Expand Down Expand Up @@ -362,7 +363,7 @@ partial interface GPUBuffer {
### Mapping Buffers at Creation ### {#buffer-mapping-at-creation}

A common need is to create a `GPUBuffer` that is already filled with some data.
This could be achieveb by creating a final buffer, then a mappable buffer, filling the mappable buffer, and then copying from the mappable to the final buffer, but this would be inefficient.
This could be achieved by creating a final buffer, then a mappable buffer, filling the mappable buffer, and then copying from the mappable to the final buffer, but this would be inefficient.
Instead this can be done by making the buffer CPU-owned at creation: we call this "mapped at creation".
All buffers can be mapped at creation, even if they don't have the `MAP_WRITE` buffer usages.
The browser will just handle the transfer of data into the buffer for the application.
Expand Down