webgpu-utils-lookup

name

webgpu-utils-lookup

description

Ground any answer about the webgpu-utils library (greggman/webgpu-utils) in its actual API before responding. Use whenever a question or task touches a webgpu-utils function, class, or option — makeShaderDataDefinitions, makeStructuredView, createBuffersAndAttributesFromArrays, createTextureFromImage(s)/Source(s), generateMipmap, primitives.*, setStructuredView, the reflected uniform/storage views, bind-group-layout generation, attribute/buffer creation, mip generation, or anything imported from 'webgpu-utils'. In the OGPU engine this library backs RenderPipeline, ComputeShader, Geometry, Texture, and IBLUtils, so it surfaces constantly — consult it before claiming a signature, option name, default, or behavior, rather than guessing from memory. Trigger even when the user doesn't name the library, if the symbol clearly belongs to it.

Answer webgpu-utils questions from the source, not from memory

webgpu-utils is small but full of non-obvious behavior: functions that mutate a passed-in view in place, reflection that keys uniforms by declared name, helpers that silently pick a texture view dimension for you, options whose defaults matter (mips, usage, viewDimension). Memory of "roughly how it works" is exactly where wrong answers come from — a misremembered option name or a stale signature compiles fine and then breaks at runtime with no error. The cost of checking is a few seconds; the cost of guessing is a silent garbage texture or a buffer written to the wrong offset. So check first.

This codebase pins webgpu-utils 1.11.0 (dist/1.x). The installed copy is the ground truth for this project — prefer it over anything you recall or find online, because online docs track latest and may have drifted.

Lookup order

1. Local types — authoritative for the installed version. The .d.ts files carry full signatures, option-object shapes, defaults, and the doc-comments (often with usage examples). Read these first:

   node_modules/webgpu-utils/dist/1.x/<module>.d.ts
   

   references/api-map.md maps every exported symbol to its .d.ts module so you can jump straight to the right file.

2. Local implementation — when behavior isn't clear from the type alone. Questions like "does it mutate the argument or return a copy?", "what does it default the format to?", "how does it decide cube vs 2d-array?" are answered by reading the compiled source:

   node_modules/webgpu-utils/dist/1.x/webgpu-utils.module.js
   

   It's readable ES — grep -n 'function <name>' to find the definition.

3. GitHub repo — for rationale, latest source, history, issues. Use when the local copy doesn't settle it, when the user asks about a version newer than 1.11.0, or when "why does it do this" needs the original TypeScript / commit context: https://github.com/greggman/webgpu-utils (source under src/, one file per module mirroring the .d.ts names). Fetch with WebFetch.

4. Typedoc site — human-readable index / cross-links. Good for browsing the API surface or linking the user somewhere: https://greggman.github.io/webgpu-utils/docs/. Fetch with WebFetch.

You do not need to walk all four every time. Stop at the first level that answers the question authoritatively — for a signature, level 1 alone is usually enough; reach for the repo/site only when local source can't answer it (design intent, newer versions, changelog).

How to apply what you find

• Quote the real thing. When you state a signature, option, or default, make it match the .d.ts you just read — exact option names, exact defaults. If you paraphrase, say so.
• Mind the version. If you cite the GitHub/typedoc surface and it differs from local 1.11.0, flag the gap — the user runs 1.11.0.
• Respect OGPU's wrappers. This engine rarely calls webgpu-utils raw; it wraps it (RenderPipeline → makeShaderDataDefinitions + makeStructuredView; Geometry → createBuffersAndAttributesFromArrays; Texture/IBLUtils → texture + mip helpers). When a question is really "how do I do X in OGPU", check how the wrapper already uses the helper (src/core/, src/utils/) before reaching for the raw call — the convention may already exist. The reflection-by-name rules (uniform block named uniforms, vs/fs entry points, t<Name> texture prefix) are OGPU conventions layered on top of the library's name-keyed reflection — see CLAUDE.md.

The two highest-traffic areas

Most OGPU questions land in one of these; know where they live.

• WGSL reflection & structured writes (data-definitions.d.ts): makeShaderDataDefinitions(code) parses WGSL into defs; makeStructuredView(def, buffer?) builds a typed view whose .set({...}) writes by field name into an ArrayBuffer; setStructuredView/ setStructuredValues write into an existing view; makeBindGroupLayoutDescriptors derives layouts. This is how every pipeline's uniforms get written — name mismatches fail silently, so verify field names against the struct.

• Geometry / vertex buffers (attribute-utils.d.ts): createBuffersAndAttributesFromArrays packs arrays into GPU buffers and emits bufferLayouts; @location is assigned by declaration order in the input object, not by name. Confirm order before trusting a binding.

For the full symbol → module table and the texture/mipmap/primitives groups, see references/api-map.md.