`externVar()`

Function in Authoring

Declare a host-provided global: the variable counterpart of externFn.

import { externVar } from 'typeshade'

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

Syntax

function externVar<T extends ShaderType>(
  name: string,
  type: T,
  opts?: { spelling?: { wgsl?: string; glsl?: string }; stage?: ExternVarDecl['stage'] },
): ExternVarHandle<KeyOf<T>>

Parameters

name string: the logical symbol name, and the default spelling on both targets.
type T extends ShaderType: its shader type, for checking every read.
optsoptional { spelling?: { wgsl?: string; glsl?: string }; stage?: ExternVarDecl['stage'] }: per-target spelling, and an advisory stage.

Return value

ExternVarHandle<KeyOf<T>>

an ExternVarHandle: .node reads the value, .decl goes into module({ externs }).

Description

A host prelude may hand a shader values such as a view matrix or a frame time as loose globals the module does not declare. externVar declares such a value abstractly. It emits nothing on either backend; what it provides is everything around the reference: type checking at each use site, a name that survives mangle, and an entry in reflect().requires (and in a fragment’s requires) so a host can check the module’s expectations against what its prelude provides.

spelling maps the logical name onto each target. When another host exposes the same value differently, as a WGSL struct member or a bound uniform in place of a GLSL prelude global, the change is confined to the spelling map.

Examples

Example

import { externVar, mat4fT } from 'typeshade'

const uMatrix = externVar('u_matrix', mat4fT, { stage: 'vertex' })
const clip = uMatrix.node.mul(worldPos) // type-checked; emits `u_matrix * …`

In the guide

Migrating a GLSL shader

Source

src/core/ir/builder.ts, line 1547, at commit 26de7be8

Edit this page Report a problem

externVar()