compileModule()

Syntax

function compileModule(
  m: ModuleDecl,
  opts?: { gpuStubs?: boolean; precision?: CpuPrecision; consoleSink?: ConsoleSink },
): CpuModule

Parameters

m ModuleDecl

the module to evaluate.

optsoptional { gpuStubs?: boolean; precision?: CpuPrecision; consoleSink?: ConsoleSink }

precision and gpuStubs, as above.

Return value

CpuModule

the compiled module: fns by name, and setBinding.

Exceptions

@link ValidationError

when the module fails a core rule, and Error when a GPU-only intrinsic is called with gpuStubs off, or when a raw statement is reached.

Description

Compile a module for the CPU: a tree-walk interpreter over the same IR the GPU backends receive, returning a CpuModule whose fns are ordinary JavaScript functions. It is the differential reference a parity test compares a GPU result against.

opts.precision picks what the arithmetic means. 'f64', the default, is the algebra oracle: every value is a JavaScript double, so the result is the mathematically intended one to 53 bits. It proves the IR picked the right operations in the right order, and it is blind by construction to f32 rounding, which only appears once the target truncates. 'f32' is a correctly-rounding f32 machine over the same IR: every f32-typed operation rounds to f32 afterwards, with infinities on overflow. Reach for 'f32' when the question is what the target computes, so a parity gate can compare at ulp scale without a tolerance wide enough to hide a real error.

opts.gpuStubs decides what happens at an operation the CPU cannot perform. A texture read, a screen-space derivative and the rest of the GPU-only intrinsics have no CPU meaning, and by default a call to one throws, since a plausible wrong number is the worst failure mode for a reference. Turn it on and each stands in for its GPU value: an opaque black texture read, a zero derivative. Do that only where a placeholder is acceptable for the test at hand.

setBinding(name, value) supplies a uniform or storage binding by its declared name, since a CPU run has no bind groups. Call it before invoking an entry that reads that binding.

A raw statement has no CPU evaluation at all. Reaching one throws, whichever target its payload was written for, because raw text is opaque to the IR and the oracle has nothing to walk.

It runs validate and autoVars first, the same passes the GPU writers run, so it rejects the same malformed modules they do.

Examples

import { compileModule } from 'typeshade'

const cpu = compileModule(MODULE, { precision: 'f32' })
cpu.setBinding('u', { scale: 2, offset: [0.5, 0.5] })
const got = cpu.fns.transform([1, 1])

Targets

In the guide

• Language guide
• The CPU oracle
• Raw statements

See also

• CpuModule
• validate
• autoVars
• compileModuleJs
• CpuPrecision

Source

src/core/oracle.ts, line 770, at commit 26de7be8