reflect()

구문

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

매개변수

m ModuleDecl

the module to describe.

opts선택 사항 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.

반환값

Reflection

the target-neutral pipeline metadata described above.

설명

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.

예제

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 }, …]

관련 가이드

• 작성 가이드
• 레이아웃과 리소스
• 출력과 리플렉션
• CPU 오라클 안내서
• 조건부 프로그램
• 기능과 확장
• fp64
• GLSL 셰이더 옮기기

함께 보기

• ReflectOptions
• hostFeaturesFor
• wgslLayout
• ModuleDecl
• module
• overrideConst
• uniformStruct
• storageBuffer

소스

src/core/reflect.ts, 868행, 커밋 26de7be8 기준