hostBlock()

구문

function hostBlock<F extends Record<string, UniformFieldSpec>>(
  typeName: string,
  at: { group: number; binding: number; as: string },
  fields: F,
  opts?: { glsl?: 'std140-block' | 'loose'; precision?: 'highp' | 'mediump' | 'lowp' },
): UniformStruct<F>

매개변수

typeName string

the struct’s type name, as the host spells it.

at { group: number; binding: number; as: string }

the WGSL group and binding slot, and as, the block variable’s name.

fields F extends Record<string, UniformFieldSpec>

the members, in the host’s declaration order.

opts선택 사항 { glsl?: 'std140-block' | 'loose'; precision?: 'highp' | 'mediump' | 'lowp' }

glsl picks the GLSL spelling; precision is a GLSL-only qualifier applied to each member of a 'loose' block (a std140 block takes the stage default).

반환값

UniformStruct<F>

the UniformStruct handle; camera.field.u_matrix is typed against the declared shape.

예외

SD0016

SD0016 when glsl: 'loose' is asked for a member the default block cannot spell.

UnsupportedFeatureError

Their names must also be unique across every loose block in the module, since flattening puts them all in one namespace; a collision throws UnsupportedFeatureError at GLSL emit.

설명

On WGSL a host-owned bind group is one unit: the host hands the module @group(0) and its layout is the authority. That is why a block is its own declaration and cannot be written as several hostUniform calls, which would describe a different program.

On WGSL it is an ordinary @group(N) @binding(M) var<uniform> block, which the shader still declares in order to read it, and reflect marks every entry owner: 'host' so a consumer knows not to build a layout for it.

On GLSL ES 3.00 the spelling is the caller’s choice, because a GLSL host prelude provides one or the other and only the matching one links:

• glsl: 'std140-block' (the default) emits layout(std140) uniform CameraUniforms { ... } u_camera;.
• glsl: 'loose' emits one uniform mat4 u_matrix; per member and rewrites every u_camera.u_matrix read to the bare u_matrix. The rewrite happens on the module’s node graph before emit, so it cannot touch an unrelated substring, it survives minify(), and reflect still describes what was emitted.

A loose block’s members must be scalars, vectors or matrices, because the default block has no spelling for a nested struct; this call checks it and throws SD0016. Their names must also be unique across every loose block in the module, since flattening puts them all in one namespace; a collision throws UnsupportedFeatureError at GLSL emit.

예제

import { hostBlock, mat4x4fT, vec2fT } from 'typeshade'

const camera = hostBlock('CameraUniforms', { group: 0, binding: 0, as: 'u_camera' }, {
  u_matrix: mat4x4fT,
  u_viewport_px: vec2fT,
}, { glsl: 'loose' })

camera.field.u_matrix // typed against the declared shape

관련 가이드

• GLSL 셰이더 옮기기

함께 보기

• hostUniform
• reflect
• UnsupportedFeatureError
• UniformStruct

소스

src/core/sot.ts, 972행, 커밋 c66579bf 기준