Specify immediate data API and WGSL <immediate> address space by shaoboyan091 · Pull Request #5423 · gpuweb/gpuweb

shaoboyan091 · 2025-10-29T08:49:07Z

Landing the immediate data API specification into the WebGPU spec. Ref to proposal: immediate-data.md.

Copilot

Pull Request Overview

This PR adds support for immediate data in WebGPU pipelines, allowing small amounts of data to be passed directly to shaders without requiring buffer bindings. This is useful for frequently changing small data like transformation matrices.

Introduces maxImmediateSize limit (64 bytes) for immediate data ranges
Adds immediateSize parameter to pipeline layouts and validation for immediate data usage
Implements setImmediateData() method for setting immediate data in encoders

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

github-actions · 2025-10-29T08:54:11Z

Previews, as seen when this build job started (fbde276):
WebGPU _{webgpu.idl | Explainer | Correspondence Reference}
WGSL _{grammar.js | wgsl.lalr.txt}

jimblandy · 2025-10-29T17:58:21Z

minutes from API committee meeting 2025-10-29

KN: Everything should be more or less done in the proposal. Is there anything else people know they want fixed before it moves forward? Shaobo has begun work on the spec PR.
JB: Does the proposal include the word-granularity initialization checks that we agreed to in Toronto?
KN: Yes
JB: Okay, cool. Then I’m not aware of any other concerns that would block drafting a PR against the spec.

kainino0x · 2025-10-31T23:01:08Z

+      <td>Invocations in the same [=shader stage=]
+      <td>[=access/read=]
+      <td>For [=immediate data=] variables.<br>
+          [=type/concrete|Concrete=] [=constructible=] [=host-shareable=] types, excluding arrays and structures containing array members.<br>


Copying Alan's comment here:
#5424 (comment)

I agree with Alan here, the "Concrete ..." part is redundant, and should be removed.

alan-baker

Copying my other requests from #5424

There ought to be either a language feature or enable extension as part of this specification.

Additionally, there need to be some updates to the Resource Interface and Resource Layout Compatibility sections in the Entry Points chapter.

dneto0

I agree with other review comments. Once those are resolved I'm happy with this landing.

dneto0 · 2025-11-04T15:34:14Z

+      <td>Invocations in the same [=shader stage=]
+      <td>[=access/read=]
+      <td>For [=immediate data=] variables.<br>
+          [=type/concrete|Concrete=] [=constructible=] [=host-shareable=] types, excluding arrays and structures containing array members.<br>


I agree with Alan here, the "Concrete ..." part is redundant, and should be removed.

mwyrzykowski · 2025-11-04T17:46:09Z

Copying my other requests from #5424

There ought to be either a language feature or enable extension as part of this specification.

Would prefer not using an enable extension since this is supported or can be easily emulated by all core devices (and compat too I think).

I.e., WGSL language extension would be my preference.

mwyrzykowski · 2025-11-05T17:13:18Z

I can't make the meeting today but this is 👍 from Apple's side. Metal doesn't have the concept of immediates and there was some discussion about this taking up a buffer slot. If the UA is using argument buffers then it would not, since a slot is already needed for dynamic data and you can reuse / share the same slot for immediates. Basically any transient data (dynamic offsets, immediates, other constants) can be passed in a single call to set[Vertex/Fragment]Bytes.

But we are also fine with this taking up a slot. This allows UAs to not have to migrate to ABs for everything for their Metal backends. I suppose its a tradeoff but either way is 👍 from Apple's side given our AB implementation is not really impacted either way.

jimblandy · 2025-11-06T22:19:54Z

minutes from WGSL committee meeting 2025-11-4

JB: PR for specifying immediate data. Understanding is this is a popular thing in graphics APIS. Think a lot of graphics folks would be happy if it was in the API and shipped. So, looks like most of the conversation has been Kai.
DN: This is a way of getting constant data into shader that is uniform. Popular because it's fast, fewer indirections. Because it's fast, it's tiny. Feature allows a single variable in the "immediate" address space which is declared at module scope, it's uniform. From a WGSL perspective, slides in with other addres spaces. Most restrictions are API side. Make sure data gets in (api call) part of the binding pipeline descriptor to say space size. Validation for space side on api side covers the variable in the WGSL shader. Single immediate space of memory used for all the shaders in a given pipeline (unified model). THere is some validation about which 32-bit words have to be set in order to supply data. Don't have to write padding. Discussion about the imprecision of padding bytes. We dont' define padding or the inverse in a structure. Kind of implied. We could/recommend cleaning that up after this lands. Otherwise, editorial feedback. TLDR; fast uniform data access in shader.
JB: Restriction against arrays, no arrays in the value, not even in struct. Is the reason that the platform level instructions for accessing odn't allow dynamic offsets?
AB: Vulkan has a restriction that it's dynamically uniform
JB: Do mention the WGSL out of bounds rules, if there are no arrays then that only applies to vectors and matrices. So, guess what's going on is the WebGPU backend needs to lift dynamic indexing of vectors and matrices in the immediate data into something. LIfting to a variable and indexing into that or something
DN: That sounds right. Saw out of bounds doesn't really apply but you're right vector and matrices does exercise that.
JB: Otherwise, editorial comments. Only remaining interesting thing is question of render bundles. Way it's specified that after bundle runs the immediate data is considered uninitialized. Chose that because it's the most restrictive and easiest to implement. If decide later due to render bundle transparency can consider relaxing this restriction. Want to start most restrictive and allow more over time. What is the status of this for CTS implementation and Dawn implementation.
DS: Think the implementation is done, modulo bug fixes. We use this mechanism to pass side channel data for Dawn. Don’t think CTS is started.
JB: Precedent I have in mind, when talking about subgroup_id, we said it looks good, and is accepted but wait for CTS before merging to main. Think the same reasoning applies here. Want to make sure we have CTS passing and the benefit from CTS before going ahead and shipping. MW has comment would prefer not using enable as it can be supported or emulated everywhere.
DN: On WGSL side because it's a new feature we want enable or feature so we can write skipping conformance tests. Agree with MW that this should be everywhere, question in my mind is emulation steals uniform buffer slot, do we worry or need wording in API that the limits possibly get eaten into. Not a language concern, but an API concern.
JB: So as far as WGSL is concerned … ok. How does this pr phrase it now, just no extension at all? Ok, seems like a good thing to fix.
MW: Perhaps an issue for API meeting. Seems the only backend which doesn't support it is metal and there are ways to do it without taking a buffer slot (probably outside the scope of this meeting)
JB: Then not a lot of discussion for this meeting. So, resolved on language extension?
MW: <thumbs up>
DN: That's my preference
JB: Mozilla is thumbs up.
RESOLUTION: Make it a language extension, PR is good, needs CTS before landing PR

Kangz · 2025-11-12T15:07:47Z

There ought to be either a language feature or enable extension as part of this specification.

@amaiorano is implementing this speculatively in Dawn, we are going with immediate_address_space, what do folks think of this name?

alan-baker · 2025-11-12T15:57:15Z

There ought to be either a language feature or enable extension as part of this specification.

@amaiorano is implementing this speculatively in Dawn, we are going with immediate_address_space, what do folks think of this name?

That works, but I'd also be ok with just immediates.

Update index.bs to include the new <immediate> address space. Ref to proposal: immediate-data.md.

Co-authored-by: alan-baker <alanbaker@google.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

They are their own thing in the shader interface, similar to override declarations

shaoboyan091 · 2026-03-23T03:25:50Z

@jimblandy Done. Added "immediate data" to both sentences in the executeBundles() paragraph:

"does not inherit the render pass's pipeline, bind groups, immediate data, or vertex and index buffers"
"pipeline, bind group, immediate data, and vertex/index buffer state is cleared"
The Reset the render pass binding state algorithm also sets each entry of [[immediate_data_set]] to false.

kainino0x

I will reread the whole PR one more time when I have a moment but I think this looks good

Co-authored-by: Kai Ninomiya <kainino1@gmail.com>

mooflu · 2026-03-30T19:19:24Z

I see maxImmediateSize is 64. Any chance to increase that to 128? I was looking into adding webgpu support to Godot and many of the their shaders have push constant size > 64. Supported limit in Vulkan core for maxPushConstantsSize is 128. Matching that would be great and simplify adoption by the various engines.

shaoboyan091 · 2026-03-31T03:01:40Z

@mooflu From implementation part, it is hard to expand to 128 bytes(as default limits) :(. We have some internal reserved push constants in implementation so we cannot expose all range as customer immediates.

From spec view, we defined maxImmediateSize here as "Default" Limits, which means, adapter might report a higher limits and you could create device by requesting higher limits.

P.S.
Default limits: https://www.w3.org/TR/webgpu/#limits
GPUAdapter reported limits: https://www.w3.org/TR/webgpu/#gpuadapter
Device request limits: https://www.w3.org/TR/webgpu/#gpudevicedescriptor

kainino0x

Final editorial review, finally!

Co-authored-by: Kai Ninomiya <kainino1@gmail.com>

…rantees sections

shaoboyan091 · 2026-04-08T04:42:57Z

@jimblandy Would you mind to do a final review for this?

kainino0x · 2026-04-08T18:58:08Z

        Values are set by {{GPUBindingCommandsMixin/setImmediates()}}.

-    : <dfn>\[[immediate_data_set]]</dfn>, of type [=list=]&lt;{{boolean}}&gt;
+    : <dfn>\[[immediate_slots_set ]]</dfn>, of type [=list=]&lt;{{boolean}}&gt;


nit: Extra space in this dfn name

shaoboyan091 · 2026-04-14T01:52:44Z

@jimblandy would you mind to take a look again on this spec PR?

shaoboyan091 requested a review from Copilot October 29, 2025 08:49

Copilot AI reviewed Oct 29, 2025

View reviewed changes

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

shaoboyan091 requested review from Kangz and kainino0x October 29, 2025 08:52

jimblandy mentioned this pull request Oct 29, 2025

[WGSL] Specify <immediate> address space #5424

Closed

kainino0x reviewed Oct 31, 2025

View reviewed changes

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs

shaoboyan091 requested review from alan-baker and kainino0x October 31, 2025 06:32

kainino0x reviewed Oct 31, 2025

View reviewed changes

kainino0x added wgsl WebGPU Shading Language Issues api WebGPU API labels Oct 31, 2025

kainino0x changed the title ~~Specify immediate data API in the WebGPU spec~~ Specify immediate data API and WGSL Oct 31, 2025

kainino0x changed the title ~~Specify immediate data API and WGSL~~ Specify immediate data API and WGSL <immediate> address space Oct 31, 2025

alan-baker requested changes Nov 1, 2025

View reviewed changes

Comment thread spec/index.bs

Kangz reviewed Nov 3, 2025

View reviewed changes

Comment thread spec/index.bs Outdated

jimblandy added this to WGSL Nov 3, 2025

jimblandy moved this to Current agenda in WGSL Nov 3, 2025

jimblandy added this to the Milestone 2 milestone Nov 3, 2025

dneto0 reviewed Nov 4, 2025

View reviewed changes

jimblandy moved this from Current agenda to Waiting on CTS in WGSL Nov 6, 2025

Kangz reviewed Nov 7, 2025

View reviewed changes

Comment thread spec/index.bs Outdated

alan-baker reviewed Nov 12, 2025

View reviewed changes

Comment thread wgsl/index.bs Outdated

mwyrzykowski reviewed Nov 12, 2025

View reviewed changes

Comment thread spec/index.bs Outdated

shaoboyan091 and others added 11 commits March 20, 2026 10:37

Specify <immediate> address space

ad13b13

Update index.bs to include the new <immediate> address space. Ref to proposal: immediate-data.md.

Update wgsl/index.bs

895beb8

Co-authored-by: alan-baker <alanbaker@google.com>

Update wgsl/index.bs

21ba7fa

Co-authored-by: alan-baker <alanbaker@google.com>

Address comments

b045b81

Address comments

f2653d8

Address comments

d33528e

Apply suggestions from code review

b8243f4

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update wgsl/index.bs

5ab1e43

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

WGSL: don't describe immediate data as part of the resource interface

08c755a

They are their own thing in the shader interface, similar to override declarations

Simplify description of max immediate variable size

e68f1c1

Address comments

3fa0d5c

shaoboyan091 force-pushed the gpu-spec branch from 2aa6328 to 3fa0d5c Compare March 20, 2026 06:39

kainino0x reviewed Mar 20, 2026

View reviewed changes

Comment thread spec/index.bs

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

Address comments in spec/index.bs.

b16cc9e

shaoboyan091 requested a review from kainino0x March 23, 2026 03:16

kainino0x reviewed Mar 24, 2026

View reviewed changes

Comment thread spec/index.bs Outdated

Update spec/index.bs

8c2b204

Co-authored-by: Kai Ninomiya <kainino1@gmail.com>

shaoboyan091 mentioned this pull request Mar 25, 2026

WebGPU: Immediates WebKit/standards-positions#640

Closed

Merge branch 'main' into gpu-spec

5cce2cd

kainino0x approved these changes Apr 8, 2026

View reviewed changes

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

Comment thread spec/index.bs Outdated

kainino0x added a commit to kainino0x/gpuweb that referenced this pull request Apr 8, 2026

[editorial] nits for gpuweb#5423 that didn't make sense to do in that PR

485b8f9

shaoboyan091 and others added 3 commits April 8, 2026 10:44

Apply suggestions from code review

589c87b

Co-authored-by: Kai Ninomiya <kainino1@gmail.com>

Address comments

87585b1

Move maxImmediateSize alignment requirement to adapter-capability-gua…

fbde276

…rantees sections

kainino0x reviewed Apr 8, 2026

View reviewed changes

Conversation

shaoboyan091 commented Oct 29, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jimblandy commented Oct 29, 2025

Uh oh!

Uh oh!

Uh oh!

kainino0x Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

dneto0 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

alan-baker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dneto0 left a comment

Choose a reason for hiding this comment

Uh oh!

dneto0 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mwyrzykowski commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mwyrzykowski commented Nov 5, 2025

Uh oh!

jimblandy commented Nov 6, 2025

Uh oh!

Uh oh!

Uh oh!

Kangz commented Nov 12, 2025

Uh oh!

alan-baker commented Nov 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shaoboyan091 commented Mar 23, 2026

Uh oh!

kainino0x left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mooflu commented Mar 30, 2026

Uh oh!

shaoboyan091 commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kainino0x left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shaoboyan091 commented Apr 8, 2026

Uh oh!

kainino0x Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

shaoboyan091 commented Apr 14, 2026

Uh oh!

github-actions bot commented Oct 29, 2025 •

edited

Loading

mwyrzykowski commented Nov 4, 2025 •

edited

Loading

shaoboyan091 commented Mar 31, 2026 •

edited

Loading