reflect WESL to JSON

[mighdoll]

The WGSL committee suggested at their 2025.04.01 meeting that they like the idea of reflection in browser core WebGPU, someday.. They don't quite know what users would want for reflection and are interested in WESL exploring the issue.

They imagine a mechanism where WebGPU could report some language neutral JSON about WGSL elements. Libraries could then use the JSON to construct host language specific bindings (for TypeScript/TypeGPU for example).

Our current reflection experiments go direct to host application specific libraries. Can we find a common JSON layer and then go from there to a application specific bindings?

[mighdoll]

cc: @jarvispact @iwoplaza

[jarvispact]

Interesting. I like the idea a lot 👍. Lets start with structs first.

In the case of timefold and typegpu we are ok with the struct name, the fieldname and type information because we compute the padding, offsets and final buffer size ourselfs. But it may be useful for others to add the byteOffset, component size and final Arraybuffer size as a info if that is known by wesl? For example:

{
  "structs": {
    "Vertex": {
      "fields": {
        "position": {
          "type": "vec3<f32>",
          "byteOffset": 0,
          "components": 3
        },
        "uv": {
          "type": "vec2<f32>",
          "byteOffset": 16, // position aligned to a vec4
          "components": 2
        }
      },
      "bufferSize": 48
    }
  }
}

So basically all the info that is necessary to generate the typedarray views:

const data = new ArrayBuffer(bufferSize);

// Example vec3: byteOffset: 0, componentSize: 3
const positionView = new Float32Array(data, byteOffset, componentSize);

// Example vec2: byteOffset: 16, componentSize: 2
const uvView= new Float32Array(data, byteOffset, componentSize);

Then the consumer can use those views to set the data into the structs/uniforms directly without even using a library. In the case where a library picks up the json we can probably do even more with less information. But then we enable both scenarios.

---

Generating static types based on a json file alone will be hard, as you loose the literal type "vec3<f32>" for fields.[name].type. It will be just of type string. As long as we find a way to get the literal types i can activate my typescript voodoo and create a type helper that will resolve the above to something like this:

type Vertex = InferFromJson<typeof jsonObj>;

// type looks like that:
{
  position: Float32Array,
  uv: Float32Array
}

// or even like that:
{
  position: [number, number, number],
  uv: [number, number]
}

This could be useful again for the consumer without using a library. Libraries could ofc further abstract and provide additional convenience features.

Both variants are already possible in timefold.

[jarvispact]

For the no-library case we could leverage json-schemas as there is also type generation tools available? 🤔 For the case where libraries pick it up, the types should not be a issue as we already demonstrated in typegpu and timefold. We could just grab the info from the json instead of the AST.

[mighdoll]

Both variants are already possible in timefold.

Nifty, mode option..

[mighdoll]

As long as we find a way to get the literal types i can activate my typescript voodoo and create a type helper

I see.. So we'd encode some type information in the JSON that'd be useful for further processing by type aware tools.

I guess we could have some api that makes the JSON available to wesl extensions (in addition to the the AST) e.g. in PluginExtension. What would that api look like? JSON per module/file? Need there be links between the JSON and the AST?

[jarvispact]

To generate TypedArray views with the correct padding and alignment we always need to start at the unform declarations i think? At least thats how i understood it. You most likely want to have a one to one mapping of uniform declaration to js object. So a nice first MVP could be to provide the json schema for each uniform declaration in the main vs/fs entrypoint. So if your entrypoint looks like this:

// some structs are imported, some are declared in this file...
import package::scene::{LightStruct};

struct EntityStruct { ... }

@group(0) @binding(0) var<uniform> camera: mat4x4<f32>;
@group(0) @binding(1) var<uniform> lights: array<LightStruct, 3>;
@group(1) @binding(0) var<uniform> entity: EntityStruct;

@vertex fn vs( ... ) -> @builtin(position) vec4f { ... }

@fragment fn fs( ... ) -> @location(0) vec4f { ... }

The json schema could have the following structure:

{
  "uniforms": {
    "camera": { "type": "mat4x4<f32>", ... },
    "lights": { "type": "array<LightStruct, 3>", ... }
    "entity": { "type": "EntityStruct", ... }
  }
}

The TS bindings may look like that:

export const Camera = {
  buffer: new ArrayBuffer(size),
  view: new Float32Array([ ... ]), // just a mat4x4
};

export const Lights = {
  buffer: new ArrayBuffer(size),
  views: [ ... ], // array of objects
};

export const Entity = {
  buffer: new ArrayBuffer(size),
  views: { ... }, // object
};

With this the consumer or a library can have js bindings for each of them and set them at the correct time in the render pipeline. That would be a good starting point at least from my perspective. Wdyt?

[iwoplaza]

I'm loving the ideas here! 💜
Making sure that there's a host-independent intermediate format for reflection as the thing we depend on for generating timefold/typegpu should allow us to:

1. Showcase the usefulness of reflection to the WebGPU committee.
2. Ensure that we're building on top of something that could become part of the standard.

Generating static types based on a json file alone will be hard, as you loose the literal type "vec3" for fields.[name].type. It will be just of type string. As long as we find a way to get the literal types i can activate my typescript voodoo and create a type helper that will resolve the above to something like this:

I agree, that's going to be tricky... especially since, given we're aiming for it to become part of the standard, it would be hard for the WebGPU API to give us a const-typed JSON on the type-level.

To generate TypedArray views with the correct padding and alignment we always need to start at the unform declarations i think? At least thats how i understood it.
I'm not 100% certain what you're referring to, could you clarify? 🙌

[mighdoll]

Continuing with the struct POC idea... what else should be in the JSON? maybe attributes? And for e.g. the components of vec, shouldn't we provide the type of the element separately e.g. elementType: "f32" and not just type: "vec2<f32>"?

Is this what we're talking about so far for the json format?

interface Reflected {
  uniforms: Record<string, VarReflection>;
  structs: Record<string, StructReflection>;
}

interface VarReflection {
  type: string; // full WGSL type (e.g. `vec3<f32>` or `EntityStruct`)
}

interface StructReflection {
  fields: MemberReflection[];
  bufferSize: number;
}

interface MemberReflection {
  name: string;
  type: string; 
  byteOffset: number;
}

interface ArrayReflection {
  elementType: string;
  length: number;
}

What should we add/change?

[stefnotch]

We should also add

• a list of entry points, and what bindings the entry point uses
• group and binding numbers
• unsized arrays

[jarvispact]

I'm not 100% certain what you're referring to, could you clarify?

@iwoplaza I mean that the padding / alignment are dependant on the uniform declaration. Thats basically the starting point on where you calculate the byteOffset for all the nested members. Take this example:

struct Foo { a: f32, b: vec2<f32> };
struct Bar { c: f32, d: vec2<f32>, foo: Foo };
@group(0) @binding(0) var<uniform> bar: array<Bar, 3>;

If the json lists the byteOffsets for each member of each struct individually it is different than when we start from the uniform declaration. At least i think this is how it works, sorry if i got that wrong. I basically reverse engineered the whole thing when i wrote my struct abstraction in timefold 😅

JSON just lists individual structs top level:

{
  "structs": {
    "Foo": { ... },
    "Bar": { ... },
  }
}

But that is probably wrong as the byteOffsets of the individual structs are different when you look at them in isolation because of nested array and struct alignment rules. But if we provide a mapping that starts at the uniform declaration and resolves them from there we end up with different byteOffsets right?

{
  "uniforms": {
    "bar": {
      "type": "array<Bar, 3>",
      "structs": {
        "Foo": { ... },
        "Bar": { ... },
      }
      },
  }
}

Again, sorry if that is not true.

---

Is this what we're talking about so far for the json format?

@mighdoll since we cannot have circular references in a JSON we would need to expand the struct definitions from the uniforms due to the reasons above right? I guess it makes sense to have the deduplicated structs on the top level as well anyway, but they might have different byteOffsets?

When creating the TypedArrayViews for a whole uniform in js you can upload them all at once in a single buffer. If we treat each struct individually the js application cannot upload it all at once anymore.

Here is a link to the byteOffset calculations done in timefold. But maybe i overcomplicated it due to lack of understanding...

[mighdoll]

I read this bit of the spec as saying that the offset of a struct needs to be set manually by the wgsl author using e.g. @align(16).

There's also this: https://webgpufundamentals.org/webgpu/lessons/resources/wgsl-offset-computer.html

@mighdoll since we cannot have circular references in a JSON we would need to expand the struct definitions from the uniforms due to the reasons above right? I guess it makes sense to have the deduplicated structs on the top level as well anyway, but they might have different byteOffsets?

I read the spec as saying that structs have different requirements to be usable in the uniform address space, but the alignment of the members doesn't change depending on how its used. e.g. the wgsl author might have to add @align(16) to one of the members, but it's not implicitly done to a struct because its used that way.

If that's right, I'm not sure but I think the byteOffset you proposed still works and is stable. The code that generates byteOffset for a member that's a struct might need to be take into account things like @align().

re: references in JSON. It is awkward. But I guess for this case we could look them up by name in the structs map?

[mighdoll]

note that once we get to thinking about more than one .wesl/.wgsl module, we'll want to think about using longer names too.. e.g. there could be multiple EntityStruct structs in different files. So maybe the type names should be qualified..., package::util::EntityStruct, etc.