threeagent.tsl — doughamil/threeagent 2.0.5

clj

Macros for writing TSL shaders as Clojure. See threeagent/tsl.cljs for the language reference and threeagent.tsl.compiler for the rewriting rules.

cljs

Write Three.js TSL shaders as Clojure.

Macros (see threeagent/tsl.clj):

• shader compile an expression into a TSL node (or a map of nodes)
• defshader defn whose body is shader code, e.g. a material's shader
• shader-fn a TSL Fn, callable like a Clojure function
• defshader-fn def + shader-fn; typed params emit a named WGSL function
• compute a compute node: (compute {:count n} body...)
• defcompute def + compute

Inside shader code, arithmetic, comparison and logic operators build nodes when any argument is a node and keep their Clojure meaning otherwise; [a b c] is a vec3; (:xyz v) swizzles; any three/tsl export can be called by its JS name or kebab-case name (position-local, mx-noise-float).

The functions below are the runtime the macros compile to. They are public so the SCI integration can reach them, and usable directly.

$ cljs

($ n)

($ n a)

($ n a b)

($ n a b c)

($ n a b c d)

($ n a b c d & more)

Call the three/tsl export named n.

Uses Reflect.apply: many exports are Fn Proxies whose get trap turns f.call(null, a) into FnNode.call(null, a), shifting every argument.

$get cljs

($get n)

The three/tsl export named n.

add cljs

and* cljs

(and* & thunks)

Evaluates thunks left to right with Clojure short-circuiting until a node shows up; from there on the rest are combined with TSL and.

assign! cljs

(assign! target value)

(set! target value) in shader code.

bit-and cljs

bit-not cljs

(bit-not x)

bit-or cljs

bit-shift-left cljs

bit-shift-right cljs

bit-xor cljs

call-fn cljs

(call-fn fn-node & args)

compute clj/s macro

(compute & args)

A compute node running the body once per invocation.

(compute {:count n :workgroup-size [64]} (let [i instance-index] (set! (nth positions i) (+ (nth positions i) (nth velocities i)))))

compute* cljs

(compute* f count workgroup-size)

cond* cljs

(cond* stmt? clauses)

clauses alternates test thunks (or :else) and body thunks. CPU tests short-circuit as in Clojure; node tests become a select chain (expressions) or an If/ElseIf/Else chain (statements).

dec cljs

(dec x)

defcompute clj/s macro

(defcompute & args)

def + compute.

defshader clj/s macro

(defshader & args)

defn whose body is shader code. Typical use is a node material's shader:

(defshader glow [{:keys [time tint]}] {:color (* tint (+ 0.5 (* 0.5 (sin time))))})

defshader-fn clj/s macro

(defshader-fn & args)

def + shader-fn. Typed params produce a WGSL function named after the var.

div cljs

eq cljs

fn-arg cljs

(fn-arg inputs i n)

Parameter i (named n) of a TSL Fn. Without a layout TSL passes an array-like; with one, an object keyed by parameter name.

fn-node cljs

(fn-node f layout)

tsl.Fn(f, layout). The result is a JS Proxy: call it with call-fn, never as a Clojure function (IFn dispatch breaks it in advanced builds).

fn-node-of cljs

(fn-node-of shader-fn)

The underlying TSL Fn of a shader-fn.

gt cljs

gte cljs

if* cljs

(if* test then else stmt?)

Node test: TSL select for expressions, If().Else() for statements. CPU test: plain Clojure if.

inc cljs

(inc x)

join cljs

(join & xs)

[a b c] in shader code. All numbers: vecN of that many components. With nodes: a JoinNode, whose size is the total component count, resolved when the shader builds - so [pos 1] with a vec3 pos is a vec4.

kw cljs

(kw x k)

(:k x) in shader code: a property (swizzle) on nodes, a lookup otherwise.

layout cljs

(layout fn-name return-type inputs)

loop-range cljs

(loop-range name start end step body)

A TSL Loop over name from start towards end by step. body gets the loop index node.

loop-while cljs

(loop-while test body)

lt cljs

lte cljs

max cljs

min cljs

mod cljs

Node: WGSL %. Numbers: cljs.core/mod.

mul cljs

neq cljs

node? cljs

(node? x)

True for TSL nodes.

not cljs

(not x)

nth cljs

(nth coll i)

(nth coll i not-found)

Node: .element(i) (arrays, buffers, matrix columns). Otherwise cljs.core/nth.

op-assign! cljs

(op-assign! method target value)

(+= target value) and friends. method is e.g. "addAssign".

or* cljs

(or* & thunks)

rem cljs

shader clj/s macro

(shader & body)

Compile the body as shader code and return the resulting TSL node, or a map of nodes when the body returns a map literal.

Bodies that use statements (set!, +=, let-var, dotimes, for-range, while, a node-conditioned when...) are wrapped in a TSL Fn.

shader-fn clj/s macro

(shader-fn & args)

A TSL Fn wrapped in a Clojure function.

(shader-fn [a b] (* a b)) ; inlined into the caller (shader-fn [a :float b :vec3] :vec3 (* a b)) ; emitted as a WGSL function (shader-fn [p :vec3] :void (set! ...)) ; statement function

shader-fn* cljs

(shader-fn* f layout arity)

Wrap a TSL Fn in a Clojure function of arity args. The Fn itself is available as (fn-node-of f).

sub cljs

T cljs

The three/tsl module.

var! cljs

(var! init)

A mutable shader variable initialised to init (let-var).