Skip to content

Specify immediate data API and WGSL <immediate> address space - #5423

Merged
Kangz merged 23 commits into
gpuweb:mainfrom
shaoboyan091:gpu-spec
May 7, 2026
Merged

Specify immediate data API and WGSL <immediate> address space#5423
Kangz merged 23 commits into
gpuweb:mainfrom
shaoboyan091:gpu-spec

Conversation

@shaoboyan091

@shaoboyan091 shaoboyan091 commented Oct 29, 2025

Copy link
Copy Markdown
Contributor

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

@shaoboyan091
shaoboyan091 requested a review from Copilot October 29, 2025 08:49
Copilot AI reviewed Oct 29, 2025
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Comment thread spec/index.bs Outdated
Comment thread spec/index.bs Outdated
@github-actions

github-actions Bot commented Oct 29, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

@jimblandy

jimblandy commented Oct 29, 2025

Copy link
Copy Markdown
Contributor
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.

@jimblandy jimblandy mentioned this pull request Oct 29, 2025
Closed
kainino0x
kainino0x reviewed Oct 31, 2025
View reviewed changes
Comment thread spec/index.bs Outdated
Comment thread spec/index.bs
kainino0x
kainino0x reviewed Oct 31, 2025
View reviewed changes
Comment thread wgsl/index.bs Outdated
@kainino0x kainino0x added wgsl WebGPU Shading Language Issues api WebGPU API labels Oct 31, 2025
@kainino0x kainino0x changed the title Specify immediate data API in the WebGPU spec Specify immediate data API and WGSL Oct 31, 2025
@kainino0x kainino0x changed the title Specify immediate data API and WGSL Specify immediate data API and WGSL <immediate> address space Oct 31, 2025
alan-baker
alan-baker requested changes Nov 1, 2025
View reviewed changes

@alan-baker alan-baker left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Comment thread spec/index.bs
Kangz
Kangz reviewed Nov 3, 2025
View reviewed changes
Comment thread spec/index.bs Outdated
@jimblandy jimblandy moved this to Current agenda in JimB WGSL planning Nov 3, 2025
@jimblandy jimblandy added this to the Milestone 2 milestone Nov 3, 2025
dneto0
dneto0 reviewed Nov 4, 2025
View reviewed changes

@dneto0 dneto0 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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

Comment thread wgsl/index.bs Outdated
Comment thread spec/index.bs
@mwyrzykowski

mwyrzykowski commented Nov 4, 2025 •
edited
Loading

Copy link
Copy Markdown

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

mwyrzykowski commented Nov 5, 2025

Copy link
Copy Markdown

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

jimblandy commented Nov 6, 2025

Copy link
Copy Markdown
Contributor
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

@jimblandy jimblandy moved this from Current agenda to Waiting on CTS in JimB WGSL planning Nov 6, 2025
Kangz
Kangz reviewed Nov 7, 2025
View reviewed changes
Comment thread spec/index.bs Outdated
alan-baker
alan-baker reviewed Nov 12, 2025
View reviewed changes
Comment thread wgsl/index.bs Outdated
@Kangz

Kangz commented Nov 12, 2025

Copy link
Copy Markdown
Contributor

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

alan-baker commented Nov 12, 2025

Copy link
Copy Markdown
Contributor

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.

mwyrzykowski
mwyrzykowski reviewed Nov 12, 2025
View reviewed changes
Comment thread spec/index.bs Outdated
@shaoboyan091

shaoboyan091 commented Apr 8, 2026

Copy link
Copy Markdown
Contributor Author

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

kainino0x
kainino0x reviewed Apr 8, 2026
View reviewed changes
Comment thread spec/index.bs Outdated
@shaoboyan091

shaoboyan091 commented Apr 14, 2026

Copy link
Copy Markdown
Contributor Author

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

@shaoboyan091

shaoboyan091 commented Apr 20, 2026

Copy link
Copy Markdown
Contributor Author

hi, @jimblandy , will you take a look?

@Vipitis Vipitis mentioned this pull request Apr 21, 2026
Merged
10 tasks
@jimblandy

jimblandy commented Apr 22, 2026

Copy link
Copy Markdown
Contributor

I'd like to give this one more look over, but I can't get to it until tomorrow (Thursday).

@shaoboyan091

shaoboyan091 commented Apr 28, 2026

Copy link
Copy Markdown
Contributor Author

Hi, @jimblandy any chance to give this PR a look?

@beaufortfrancois beaufortfrancois mentioned this pull request Apr 29, 2026
Merged
@shaoboyan091

shaoboyan091 commented May 5, 2026

Copy link
Copy Markdown
Contributor Author

Hi, @jimblandy any chance to give this PR a look?

jimblandy
jimblandy reviewed May 6, 2026
View reviewed changes
Comment thread spec/index.bs Outdated
jimblandy
jimblandy approved these changes May 6, 2026
View reviewed changes

@jimblandy jimblandy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Aside from the editorial comment I left above, this looks great. Thank you, @shaoboyan091 !

@shaoboyan091

shaoboyan091 commented May 7, 2026

Copy link
Copy Markdown
Contributor Author

Thanks all for your reviewing. I'll address all remain comments and land this.

@shaoboyan091
Merge branch 'main' into gpu-spec
e77030a
@shaoboyan091
Address review comments on immediate data validation
7cc2469 
- Remove extra space in [[immediate_slots_set]] dfn name
- Move pipeline layout/size lookups inside the validusage block to
  match the pattern in Validate encoder bind groups, so the null
  check on pipeline appears before its layout is dereferenced
@shaoboyan091

shaoboyan091 commented May 7, 2026

Copy link
Copy Markdown
Contributor Author

I'll land this if no objections :)

kainino0x
kainino0x reviewed May 7, 2026
View reviewed changes
Comment thread spec/index.bs
kainino0x
kainino0x reviewed May 7, 2026
View reviewed changes
Comment thread spec/index.bs Outdated
@Kangz
Kangz merged commit 6bf9e46 into gpuweb:main May 7, 2026
4 checks passed
@github-project-automation github-project-automation Bot moved this from Waiting on CTS to Done in JimB WGSL planning May 7, 2026
Kangz pushed a commit to webgpu-native/webgpu-headers that referenced this pull request May 7, 2026
@beaufortfrancois
Add missing setImmediates method (#588)
673658b 
This PR adds missing the `setImmediates` method as described in
gpuweb/gpuweb#5423
@Kangz

Kangz commented May 11, 2026

Copy link
Copy Markdown
Contributor
GPU Web WG 2026-05-06 Atlantic-time
  • JB: only question is if we should be using ?. in certain places (“validate immediate data” algorithm)
    • Verbal approval
  • MW: looks good to me
  • CW: Will note the comments.

@Absulit Absulit mentioned this pull request May 23, 2026
Open
juj added a commit to juj/wasm_webgpu that referenced this pull request May 28, 2026
@juj
IDL: Add support for wgpu_encoder_set_immediates. gpuweb/gpuweb#5423
8f79dd2
@Kangz Kangz mentioned this pull request Jun 3, 2026
Merged
@Vipitis Vipitis mentioned this pull request Jun 24, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kainino0x kainino0x kainino0x approved these changes
@dneto0 dneto0 dneto0 left review comments
Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@jimblandy jimblandy jimblandy approved these changes
@mwyrzykowski mwyrzykowski mwyrzykowski approved these changes
@dj2 dj2 Awaiting requested review from dj2
@alan-baker alan-baker Awaiting requested review from alan-baker
@Kangz Kangz Awaiting requested review from Kangz

Assignees

No one assigned

Labels

api WebGPU API wgsl WebGPU Shading Language Issues

Projects

JimB WGSL planning
Status: Done

Milestone

Milestone 2

Development

Successfully merging this pull request may close these issues.

10 participants

@shaoboyan091 @jimblandy @mwyrzykowski @Kangz @alan-baker @dneto0 @kainino0x @mooflu @dj2