SpectrumBuildOptions interface

Per-Spectrum-pipeline build-time knobs. All fields are optional; an unset SpectrumBuildOptions matches Spectrum’s historic default behaviour exactly.

Signature:

export interface SpectrumBuildOptions

Properties

Property Type Description

Property	Type	Description
maxThreads?	number	(Optional) Max threads the pipeline may use at runtime. - `0` (default): emit `parallel(yo)` directives; runtime uses all available cores. Lowest per-frame latency; binds more CPU per pipeline. - `1`: single-thread schedule — skip parallel directives entirely. The kernel runs end-to-end on the calling thread with zero Halide worker-pool / queue / sync overhead. Use for workflows that comfortably sustain their target frame rate on one core, and where CPU cost per pipeline matters more than per-call latency (e.g. many concurrent low-load streams on one host). - `>= 2`: cap. Currently treated as auto for emission; a runtime thread-pool cap is a follow-up. IMPORTANT: `maxThreads: 1` is fundamentally different from binding the process to one CPU via `taskset` / `cpuset`. Pinning still causes parallel directives to execute — workers spawn, queue and sync overhead happens, all forced to time-share one core. That can be 10-25× slower than the actual kernel. `maxThreads: 1` makes the SCHEDULE itself serial so the runtime doesn’t engage at all.
precision?	SpectrumPrecisionPreference	(Optional) Precision-vs-performance preference. Defaults to `"highFidelity"`. See SpectrumPrecisionPreference.

maxThreads?

number

(Optional) Max threads the pipeline may use at runtime.

- 0 (default): emit parallel(yo) directives; runtime uses all available cores. Lowest per-frame latency; binds more CPU per pipeline. - 1: single-thread schedule — skip parallel directives entirely. The kernel runs end-to-end on the calling thread with zero Halide worker-pool / queue / sync overhead. Use for workflows that comfortably sustain their target frame rate on one core, and where CPU cost per pipeline matters more than per-call latency (e.g. many concurrent low-load streams on one host). - >= 2: cap. Currently treated as auto for emission; a runtime thread-pool cap is a follow-up.

IMPORTANT: maxThreads: 1 is fundamentally different from binding the process to one CPU via taskset / cpuset. Pinning still causes parallel directives to execute — workers spawn, queue and sync overhead happens, all forced to time-share one core. That can be 10-25× slower than the actual kernel. maxThreads: 1 makes the SCHEDULE itself serial so the runtime doesn’t engage at all.

precision?

SpectrumPrecisionPreference

(Optional) Precision-vs-performance preference. Defaults to "highFidelity". See SpectrumPrecisionPreference.