lfx

README

LFX

LFX is a small DSL and toolchain for procedural lighting effects. An LFX program evaluates a single point in a lighting layout at a normalized phase value, then returns a scalar that a host can use to drive brightness, color mixing, or other effect behavior.

This repository contains:

• the language frontend and compiler pipeline
• a command-line tool for parsing, checking, sampling, and emitting WGSL
• a Wails-based preview app for experimenting with effects in a UI
• example effects and the language reference

Quick Start

go test ./...
go run ./cmd/lfx check effects/fill_iris.lfx

Command-Line Tool

The CLI lives in cmd/lfx and supports these subcommands:

• parse - parse a source file and print the AST as JSON
• check - parse, resolve imports, and run semantic validation
• graph - print the resolved import graph as JSON
• sample - evaluate an effect against a layout JSON file
• emit-wgsl - lower an effect and print WGSL

Examples:

go run ./cmd/lfx parse effects/fill_iris.lfx
go run ./cmd/lfx check effects/fill_iris.lfx
go run ./cmd/lfx graph effects/fill_iris.lfx
go run ./cmd/lfx emit-wgsl effects/fill_iris.lfx
go run ./cmd/lfx sample --layout layout.json --phase 0.5 effects/fill_iris.lfx

The sample command expects a layout JSON file with the following shape:

{
	"width": 4,
	"height": 2,
	"points": [
		{"index": 0, "x": 0, "y": 0},
		{"index": 1, "x": 1, "y": 0}
	]
}

You can also pass parameter overrides with repeated --param name=value flags, for example:

go run ./cmd/lfx sample --layout layout.json --phase 0.5 --param intensity=0.75 effects/fill_iris.lfx

Preview App

The lfx-preview/ directory contains a separate Wails application for interactive effect previewing.

cd lfx-preview
wails dev

For a production build:

cd lfx-preview
wails build

Language Reference

The current language description is documented in docs/LANGUAGE.md. It covers the source format, imports, parameters, presets, expressions, builtins, and the semantic rules enforced by this repository.

Repository Layout

• cmd/lfx - CLI entry point
• compiler - parse, resolve, validate, and lower pipeline
• parser - lexer, AST, and parser
• modules - import graph construction and resolution
• sema - semantic checks and identifier resolution
• lower - AST-to-IR lowering
• ir - shared intermediate representation
• runtime - layouts, params, presets, and sampling contracts
• backend - CPU evaluator and WGSL backend
• stdlib - built-in library modules
• effects - example effect programs
• lfx-preview - Wails preview application

Notes

• The module path is github.com/BenStokmans/lfx.
• The project targets Go 1.26.1.
• Import resolution defaults to the repository roots under stdlib/, effects/, and the repo root unless a different base directory is supplied.

Documentation

Index

• type BackendKind
• type Engine
  • func LoadFile(path string, opts Options) (*Engine, error)
  • func (e *Engine) Close() error
  • func (e *Engine) OutputChannels() int
  • func (e *Engine) Params() []ir.ParamSpec
  • func (e *Engine) SamplePoint(layout runtime.Layout, idx int, phase float32, params *runtime.BoundParams) ([]float32, error)
  • func (e *Engine) SamplePoints(layout runtime.Layout, indices []int, phase float32, ...) ([]float32, error)
• type Options

Types

type BackendKind

type BackendKind int

BackendKind selects the evaluation backend for an Engine.

const (
	// BackendCPU evaluates effects on the CPU. Available under all build configurations.
	BackendCPU BackendKind = iota
	// BackendGPU evaluates effects on the GPU via WebGPU compute shaders.
	// Requires CGO_ENABLED=0.
	BackendGPU
)

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is a compiled LFX effect ready for evaluation. It is not goroutine-safe.

func LoadFile

func LoadFile(path string, opts Options) (*Engine, error)

LoadFile compiles the .lfx file at path and returns an Engine backed by the selected backend. Call engine.Close() when done to release any GPU resources.

func (*Engine) Close

func (e *Engine) Close() error

Close releases any resources held by the Engine. For GPU backends this releases the GPU device and all associated buffers. Safe to call on a nil Engine.

func (*Engine) OutputChannels

func (e *Engine) OutputChannels() int

OutputChannels returns the number of output channels: 1 (scalar), 3 (RGB), or 4 (RGBW).

func (*Engine) Params

func (e *Engine) Params() []ir.ParamSpec

Params returns the effect's parameter specifications. Use with runtime.Bind to create a *runtime.BoundParams for sampling.

func (*Engine) SamplePoint

func (e *Engine) SamplePoint(layout runtime.Layout, idx int, phase float32, params *runtime.BoundParams) ([]float32, error)

SamplePoint evaluates the effect at a single point. Returns one float32 per output channel (clamped to [0, 1]).

func (*Engine) SamplePoints

func (e *Engine) SamplePoints(layout runtime.Layout, indices []int, phase float32, params *runtime.BoundParams) ([]float32, error)

SamplePoints evaluates the effect at multiple points. Returns a flat []float32 of length len(indices) * OutputChannels().

type Options

type Options struct {
	// Backend selects the evaluation backend. Defaults to BackendCPU.
	Backend BackendKind
	// GPUBackend selects the GPU backend when Backend == BackendGPU.
	// Accepted values: "auto" (default), "metal", "vulkan", "dx12", "gl".
	GPUBackend string
	// BaseDir is the root directory for resolving module imports.
	// If empty, LoadFile attempts to detect it from the source file path.
	BaseDir string
	// Resolver overrides the default module resolver. If nil, the file-system
	// resolver rooted at BaseDir is used.
	Resolver modules.Resolver
}

Options configures LoadFile.