`reflect()`

Function in Reflection

Recover a module's pipeline metadata from its IR.

import { reflect } from 'typeshade'

The signature, the description and the examples come from the compiler's own source at commit 26de7be8.

Syntax

function reflect(m: ModuleDecl, opts?: ReflectOptions): Reflection

Parameters

m ModuleDecl: the module to describe.
optsoptional ReflectOptions: the emit facts that change what a host must bind, the fp64 flavour among them. Pass the same values the emit will get; a default here that disagrees with the emit describes a different program.

Return value

Reflection

the target-neutral pipeline metadata described above.

Description

Recover a module’s pipeline metadata from its IR. It is what a host reads to build bind groups, write uniform buffers, describe vertex state and check device features, without parsing a line of emitted source.

The result carries:

bindGroups: every declared binding, sorted by group then binding, each with its name, address space, access mode, resource kind, owner, and the stages that reference it. It also includes the bindings the f64 emulation adds on the author’s behalf, the _fp64 guard texture among them (see ReflectOptions), because a host builds its bind group from this list and a binding missing here is a binding never bound.
uniforms and storage: std140 and std430 struct layouts, per field offset, align and size plus the struct’s own size and alignment. This is where a byte offset comes from, so nothing counts them by hand.
vertex: the vertex entry’s @location attributes with their offsets and the array stride. Offsets are std430-aligned, each field rounded up to its type’s alignment.
entries: one signature per entry point, with its stage, its workgroup size for a compute entry, its input and output types, its structured location and builtin interface, and portable when the kernel declares that tier.
requiredFeatures: every capability the emit needs, sorted and deduplicated. It covers the capabilities derived from the module’s shape (a storage binding, a compute entry, a multisampled texture load), the capabilities the module declared in enables, and the closure over implication, so a module declaring float32Blend also reports floatRenderTarget, since blending into a float target needs that target to be colour-renderable first. The ids are neutral, so translate them through hostFeaturesFor for one target.
overrides: each specialization constant’s name, type and default, the values a host pins through pipeline constants or a define header.
requires: the host-provided globals the module references and does not declare.

A texture binding reports three more fields a host needs to create a matching view and layout. textureDim is '2d', '2d-ms', '2d-array', 'cube', '3d', '1d' or 'cube-array', and textureElem is the texel element, f32, u32 or i32. Both axes are needed: WebGPU’s sampleType must be 'uint' or 'sint' for an integer texture, and WebGL2 must back one with an integer internal format. Getting that pairing wrong raises nothing on WebGL2, since a texture whose format disagrees with its sampler type is merely incomplete and reads zero. sampleType is the layout’s own word for it, 'depth', 'uint', 'sint', 'float' or 'unfilterable-float': an f32 texture is 'float' when a call of an entry pairs it with a sampler, and 'unfilterable-float' when the entries only load, measure or count it, which a 32-bit float format needs.

Reflection is read-only over the IR and never runs on the emit path. It takes a module and never a backend, which is why every id it reports is target-neutral.

wgslLayout is the same offset engine on its own, for a single struct with no module around it.

Examples

Example

import { reflect, hostFeaturesFor, wgslBackend } from 'typeshade'

const r = reflect(MODULE)
const device = await adapter.requestDevice({
  requiredFeatures: hostFeaturesFor(wgslBackend, r.requiredFeatures),
})
r.uniforms[0].fields // [{ name: 'mvp', offset: 0, size: 64, align: 16 }, …]

In the guide

Source

src/core/reflect.ts, line 868, at commit 26de7be8

Edit this page Report a problem

reflect()