Skip to content

Allow creating mappable buffer with more usages as optional features #5108

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

Open
Jiawei-Shao wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Allow creating mappable buffer with more usages as optional features #5108

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b68626
Add optional feature "buffer-map-extended-usages"
Jiawei-Shao Mar 18, 2025
8675390
Consider more GPU-writable buffer usages in MAP_WRITE
Jiawei-Shao Mar 18, 2025
7765b87
Add definition of `GPU-writable buffer usages`
Jiawei-Shao Mar 19, 2025
3d39151
Fix definition of `GPU-writable buffer usages`
Jiawei-Shao Mar 19, 2025
cad2e84
Merge branch 'main' into add-buffer-map-extended-usages
Jiawei-Shao Apr 7, 2025
44266f8
Split "buffer-map-extended-usages" into three features
Jiawei-Shao Apr 8, 2025
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
84 changes: 67 additions & 17 deletions spec/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2879,6 +2879,7 @@ enum GPUFeatureName {
"clip-distances",
"dual-source-blending",
"subgroups",
"buffer-map-extended-usages",
};
</script>

Expand Down Expand Up @@ -3037,6 +3038,17 @@ to.
<!-- As needed, compute more allowed usages based on the features enabled on the device. -->
</div>

<div algorithm data-timeline=const>
A {{GPUDevice}}'s <dfn dfn>GPU-writable buffer usages</dfn> are:

- Always allowed:
{{GPUBufferUsage/COPY_DST}},
{{GPUBufferUsage/STORAGE}},
{{GPUBufferUsage/QUERY_RESOLVE}}

<!-- As needed, compute more allowed usages based on the features enabled on the device. -->
</div>

## Example ## {#initialization-examples}

<div class=example>
Expand Down Expand Up @@ -3348,14 +3360,16 @@ The {{GPUBufferUsage}} flags determine how a {{GPUBuffer}} may be used after its
The buffer can be mapped for reading. (Example: calling {{GPUBuffer/mapAsync()}} with
{{GPUMapMode/READ|GPUMapMode.READ}})

May only be combined with {{GPUBufferUsage/COPY_DST}}.
May only be combined with {{GPUBufferUsage/COPY_DST}} when
{{GPUFeatureName/buffer-map-extended-usages}} is not enabled.
Comment thread
Jiawei-Shao marked this conversation as resolved.
Outdated

: <dfn>MAP_WRITE</dfn>
::
The buffer can be mapped for writing. (Example: calling {{GPUBuffer/mapAsync()}} with
{{GPUMapMode/WRITE|GPUMapMode.WRITE}})

May only be combined with {{GPUBufferUsage/COPY_SRC}}.
May only be combined with {{GPUBufferUsage/COPY_SRC}} when
{{GPUFeatureName/buffer-map-extended-usages}} is not enabled.
Comment thread
Jiawei-Shao marked this conversation as resolved.
Outdated

: <dfn>COPY_SRC</dfn>
::
Expand Down Expand Up @@ -3448,12 +3462,13 @@ The {{GPUBufferUsage}} flags determine how a {{GPUBuffer}} may be used after its
- |descriptor|.{{GPUBufferDescriptor/usage}} must not be 0.
- |descriptor|.{{GPUBufferDescriptor/usage}} must be a subset of the
[=allowed buffer usages=] for |this|.
- If |descriptor|.{{GPUBufferDescriptor/usage}} contains {{GPUBufferUsage/MAP_READ}}:
- |descriptor|.{{GPUBufferDescriptor/usage}} must contain no other flags
except {{GPUBufferUsage/COPY_DST}}.
- If |descriptor|.{{GPUBufferDescriptor/usage}} contains {{GPUBufferUsage/MAP_WRITE}}:
- |descriptor|.{{GPUBufferDescriptor/usage}} must contain no other flags
except {{GPUBufferUsage/COPY_SRC}}.
- If {{GPUFeatureName/buffer-map-extended-usages}} is not enabled on |this|:
- If |descriptor|.{{GPUBufferDescriptor/usage}} contains {{GPUBufferUsage/MAP_READ}}:
- |descriptor|.{{GPUBufferDescriptor/usage}} must contain no other flags
except {{GPUBufferUsage/COPY_DST}}.
- If |descriptor|.{{GPUBufferDescriptor/usage}} contains {{GPUBufferUsage/MAP_WRITE}}:
- |descriptor|.{{GPUBufferDescriptor/usage}} must contain no other flags
except {{GPUBufferUsage/COPY_SRC}}.
- If |descriptor|.{{GPUBufferDescriptor/size}} must be &le;
|this|.{{GPUObjectBase/[[device]]}}.{{device/[[limits]]}}.{{supported limits/maxBufferSize}}.
- If |descriptor|.{{GPUBufferDescriptor/mappedAtCreation}} is `true`:
Expand Down Expand Up @@ -3582,21 +3597,40 @@ The {{GPUMapMode}} flags determine how a {{GPUBuffer}} is mapped when calling
Only valid with buffers created with the {{GPUBufferUsage/MAP_READ}} usage.

Once the buffer is mapped, calls to {{GPUBuffer/getMappedRange()}} will return an
{{ArrayBuffer}} containing the buffer's current values. Changes to the returned
{{ArrayBuffer}} will be discarded after {{GPUBuffer/unmap()}} is called.
{{ArrayBuffer}} containing the buffer's current values.

Changes to the returned {{ArrayBuffer}} will be discarded after {{GPUBuffer/unmap()}} is
called.

: <dfn>WRITE</dfn>
::
Only valid with buffers created with the {{GPUBufferUsage/MAP_WRITE}} usage.

When the buffer is created without [=GPU-writable buffer usages=]:
Once the buffer is mapped, calls to {{GPUBuffer/getMappedRange()}} will return an
{{ArrayBuffer}} containing the buffer’s current values.

When the buffer is created with [=GPU-writable buffer usages=]:
Once the buffer is mapped, calls to {{GPUBuffer/getMappedRange()}} will return an
{{ArrayBuffer}} containing the buffer's current values. Changes to the returned
{{ArrayBuffer}} will be stored in the {{GPUBuffer}} after {{GPUBuffer/unmap()}} is called.
{{ArrayBuffer}} containing the default initialized data (zeros) or data written by the
webpage during a previous mapping.
Copy link
Copy Markdown
Contributor

@kainino0x kainino0x Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to be clear, this is allowing either of two behaviors?

For better portability we could clear the map region every time. I wonder, would that be too expensive? (How much of the benefit would we lose from avoiding the copyB2B in today's map-write-then-copy pattern?) The region could even be cleared before mapping by the GPU (which might have higher memory bandwidth than the CPU).

Maybe if there are really cases where effectively READ|WRITE would be more efficient than WRITE we could have the browser provide a hint about which one to use.

Copy link
Copy Markdown
Contributor Author

@Jiawei-Shao Jiawei-Shao Apr 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to be clear, this is allowing either of two behaviors?

This comes from a note in the current SPEC. Here I mean for the first time buffer.getMappedData() is called after a write-only mapping, the data in the returned array buffer should be all zeros, and since the second time the array buffer will contain the data written by the webpage during a previous mapping.

or better portability we could clear the map region every time. I wonder, would that be too expensive?

Obviously clearing the map region every time is expensive and unnecessary. With the mentioned behavior we don't need to either clear or read the data back from the GPU when non-triply mapping is used.

Maybe if there are really cases where effectively READ|WRITE would be more efficient than WRITE we could have the browser provide a hint about which one to use.

When triply mapping is supported on CPU-cached UMA (e.g. on Intel iGPUs), we can directly get the GPU data through buffer.getMappedData() without any other operations. So I add the feature "buffer-map-write-with-extended-usages-and-gpu-data" for the best performance of data uploading on this architecture.

The feature "buffer-map-write-with-extended-usages" also works for CPU-cached UMA with non-triply mapping, and it is for the best performance of data uploading on non-triply mapping on non-CPU-cached UMA and ReBAR, where only write in sequence or memcpy is much more performant compared with randomly write.

Maybe if there are really cases where effectively READ|WRITE would be more efficient than WRITE we could have the browser provide a hint about which one to use.

I feel it strange to use READ together with WRITE because MAP_READ should keep data on GPU unchanged. For such use case I decide to use "MAP_WRITE with current GPU data in the array buffer" instead.


Changes to the returned {{ArrayBuffer}} will be stored in the buffer after
{{GPUBuffer/unmap()}} is called.

Note: Write-only mapping will never return values produced by the GPU.
Copy link
Copy Markdown

@mwyrzykowski mwyrzykowski Mar 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this restriction necessary? Won't it result in an extra copy of the data for write only mappings on UMA systems?

I think it would be preferable to state that reading the contents of a write only mappings are undefined (or zero-ed?) in this case.

Copy link
Copy Markdown
Contributor Author

@Jiawei-Shao Jiawei-Shao Mar 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Won't it result in an extra copy of the data for write only mappings on UMA systems?

It is mainly because currently in Chromium a copy is always needed because we cannot access the mapped pointer from GPU resources directly in the JS side. We can discuss more about this issue in the WG meeting.

Copy link
Copy Markdown

@mwyrzykowski mwyrzykowski Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have the same restriction in WebKit too, perhaps this is a non-issue.

Copy link
Copy Markdown
Contributor

@kainino0x kainino0x Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be preferable to state that reading the contents of a write only mappings are undefined (or zero-ed?) in this case.

We couldn't make it fully undefined, at most we could add a third option for what gets returned. Hard to say if the performance would be any better better if we allowed it. It would require cache flushes or something to make sure you don't get unsafe undefined values.

And of course for portability reasons we really don't want anyone to rely on data getting read back on write-only mappings. But that's probably not a huge concern.


: <dfn>READ|WRITE</dfn>
::
Only valid with buffers created with the {{GPUBufferUsage/MAP_READ}} and
{{GPUBufferUsage/MAP_WRITE}} usage.

Once the buffer is mapped, calls to {{GPUBuffer/getMappedRange()}} will return an
{{ArrayBuffer}} containing the buffer's current values.

Changes to the returned {{ArrayBuffer}} will be stored in the buffer after
{{GPUBuffer/unmap()}} is called.

Note: Since the {{GPUBufferUsage/MAP_WRITE}} buffer usage may only be combined with the
{{GPUBufferUsage/COPY_SRC}} buffer usage, mapping for writing can never return values
produced by the GPU, and the returned {{ArrayBuffer}} will only ever contain the default
initialized data (zeros) or data written by the webpage during a previous mapping.
</dl>

{{GPUBuffer}} has the following methods:
Expand Down Expand Up @@ -3670,7 +3704,8 @@ The {{GPUMapMode}} flags determine how a {{GPUBuffer}} is mapped when calling
- |rangeSize| is a multiple of 4.
- |offset| + |rangeSize| &le; |this|.{{GPUBuffer/size}}
- |mode| contains only bits defined in {{GPUMapMode}}.
- |mode| contains exactly one of {{GPUMapMode/READ}} or {{GPUMapMode/WRITE}}.
- If {{GPUFeatureName/buffer-map-extended-usages}} is not enabled on |this|.device:
- |mode| contains exactly one of {{GPUMapMode/READ}} or {{GPUMapMode/WRITE}}.
- If |mode| contains {{GPUMapMode/READ}} then |this|.{{GPUBuffer/usage}} must contain {{GPUBufferUsage/MAP_READ}}.
- If |mode| contains {{GPUMapMode/WRITE}} then |this|.{{GPUBuffer/usage}} must contain {{GPUBufferUsage/MAP_WRITE}}.
</div>
Expand Down Expand Up @@ -16660,6 +16695,21 @@ expose real values whenever the feature is available on the adapter:
- New WGSL extensions:
- [=extension/subgroups=]

<h3 id=dom-gpufeaturename-buffer-map-extended-usages data-dfn-type=enum-value data-dfn-for=GPUFeatureName>`"buffer-map-extended-usages"`
</h3>

Allows the creation of mappable {{GPUBuffer}}s with any other {{GPUBufferUsage}} flags, and allows
setting both {{GPUMapMode/READ}} and {{GPUMapMode/WRITE}} bits as a valid map mode in
{{GPUBuffer}}.{{GPUBuffer/mapAsync()}}.

This feature adds the following [=optional API surfaces=]:
- Allows the use of {{GPUBufferUsage/MAP_READ}} with any other {{GPUBufferUsage}} flags as
|descriptor|.{{GPUBufferDescriptor/usage}} in the creation of {{GPUBuffer}}s.
- Allows the use of {{GPUBufferUsage/MAP_WRITE}} with any other {{GPUBufferUsage}} flags as
|descriptor|.{{GPUBufferDescriptor/usage}} in the creation of {{GPUBuffer}}s.
- Allows setting both {{GPUMapMode/READ}} and {{GPUMapMode/WRITE}} bits in the `mode` parameter of
{{GPUBuffer}}.{{GPUBuffer/mapAsync()}}.
Comment thread
Jiawei-Shao marked this conversation as resolved.
Outdated

# Appendices # {#appendices}

## Texture Format Capabilities ## {#texture-format-caps}
Expand Down