This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Operator Reference
Every operator of the shader language, by category. Operators named after Common Lisp's are cl's own symbols and mean what they mean there, within the limits of where shader code is not Lisp. The others are exported by cl-gsl.
"Per component" means an operator applies to each component of a vector, or each component of a matrix, independently.
(shader-documentation 'name) gives each operator's own documentation at the REPL.
Binds each variable to its value, all computed before any is bound. A variable's type is its value's.
(let* ((var value) ...) body ...)
As let, but each value sees the variables before it.
(progn form ...)
Evaluates the forms in order; the last gives the value.
(if test then [else])
then if the :bool test is true, else else. Gives a value if both branches give one of the same type.
(when test form ...), (unless test form ...)
Evaluates the forms if the test is true, or false.
(cond (test form ...) ... [(t form ...)])
The forms of the first clause whose test is true. Gives a value if it ends with a t clause and every clause gives one of the same type.
(case key ((k ...) form ...) ... [(otherwise form ...)])
The forms of the first clause that lists the key's value, compared with =, or the otherwise or t clause. Keys are written in the code. A clause may name one key without a list.
(and b ...), (or b ...)
Short-circuiting, on :bools.
(not b)
Negation of a :bool, or per component of a vector of :bools.
(the type value)
value, which must be of type. An integer literal becomes a :float or :uint.
Loops
Form
Meaning
(dotimes (var count [result]) body ...)
Runs the body count times, an :int or :uint evaluated once, with var of the same type counting from 0; then gives result, with var bound to count.
(loop form ...)
Runs the forms over and over until return. Only the simple loop; count with dotimes.
(return [value])
Leaves the innermost dotimes or loop, which gives value, or no value.
Several values
Form
Meaning
(values a b ...)
Several values. Where one is wanted, the first is used and the rest are evaluated and dropped. A function, or a stage as its outputs, returns them all.
(multiple-value-bind (var ...) form body ...)
Binds the variables to the values of form. Extra values are dropped.
(nth-value n form)
Value n, from 0, of form. n is written in the code.
(multiple-value-setq (var ...) form)
Assigns the values to the variables, and gives the first.
(multiple-value-prog1 first form ...)
Evaluates the forms in order and gives the values of first.
(multiple-value-call #'function form ...)
Calls function with the values of every form as its arguments.
Local definitions
Form
Meaning
(flet ((name ((param type) ...) body ...) ...) body ...)
Local functions. Each sees the variables around the flet, and assigning one changes it outside too. They do not see each other.
(labels (...) body ...)
As flet, but the functions see each other. None may call itself, directly or not.
(macrolet ((name lambda-list body ...) ...) body ...)
Local shader macros, whose bodies are Lisp, run as the code is checked.
(symbol-macrolet ((symbol expansion) ...) body ...)
Each symbol stands for its expansion; setf of it assigns the expansion.
(funcall #'name argument ...)
Calls the shader function name, as (name argument ...) does.
Assignment
Form
Meaning
(setf place value ...)
Assigns each value to its place, and gives the last. The value has the place's type.
(setq var value ...)
Assigns each value to its variable.
(incf place [delta]), (decf place [delta])
Adds or subtracts delta, 1 by default, and gives the new value.
Places are variables, (x v) and the other components, (swizzle v :xy) without repeats, (aref object i), struct accessors, (slot-value struct 'slot), and slots named in with-slots. Uniforms and shader variables are not places.
Arithmetic
Form
Meaning
(+ a b ...)
Sum. Vectors and matrices add per component; a scalar adds to every component.
(- a b ...), (- a)
Difference, or negation.
(* a b ...)
Product. Two vectors multiply per component. Matrix × vector, vector × matrix and matrix × matrix are linear algebra products.
(/ a b ...)
Quotient. Integers divide with truncation, as in GLSL.
(1+ n), (1- n)
Plus or minus 1.
(abs x)
Absolute value, per component. Of a complex number, its magnitude.
(signum x)
-1, 0 or 1 by the sign, per component.
(min a b ...), (max a b ...)
Least or greatest, per component.
(fma a b c)
a × b + c, per component, rounded once where the GPU can.
Scalars and vectors combine when their component types agree: (* 2 v) and (* v 0.5) work; (+ v (vec2 1)) with a :vec3v does not. A :double and a :float do not combine.
Division and rounding
Form
Meaning
(floor n [d]), (ceiling n [d]), (truncate n [d]), (round n [d])
n divided by d, 1 by default, rounded down, up, toward zero, or to the nearest (halves to even): as a float for floats and an integer for integers; then the remainder, as two values, as in Lisp. Per component for floats; integers are scalars.
(ffloor n [d]), (fceiling n [d]), (ftruncate n [d]), (fround n [d])
The same, with a float quotient.
(mod n d)
The remainder of floor, with the sign of d.
(rem n d)
The remainder of truncate, with the sign of n.
(fract x)
x minus (floor x), per component.
Comparison and predicates
Form
Meaning
(< a b ...), (> a b ...), (<= a b ...), (>= a b ...)
True if the arguments are in order. Two vectors compare per component, giving a vector of :bools.
(= a b ...)
True if all are equal. Two vectors compare per component; matrices, structs and arrays compare whole.
(/= a b ...)
True if no two are equal; per component for two vectors.
(any v), (all v)
True if any, or every, component of a vector of :bools is true. (all (= a b)) tests two vectors for equality.
(zerop n), (plusp n), (minusp n)
Sign tests of a scalar.
(evenp i), (oddp i)
Parity of an :int or :uint.
(float-nan-p x), (float-infinity-p x)
True where x is a NaN, or an infinity, per component.
Exponents, logarithms and roots
Form
Meaning
(exp x)
e to the power x, per component.
(expt base power)
base to the power power, per component. An integer power from -4 to 4, written in the code, multiplies, so it suits a negative base and integers; a base of 2 written in the code is GLSL's exp2; otherwise both are floats, and a negative base is undefined.
(log n [base])
Logarithm, natural by default, per component. A base of 2 written in the code is GLSL's log2.
(sqrt x)
Square root, per component.
(inverse-sqrt x)
1 / sqrt(x), per component.
(isqrt i)
The greatest integer whose square is at most the :int or :uinti.
Trigonometry
Angles are in radians. All work per component, on floats.
Form
Meaning
(sin x), (cos x), (tan x)
(asin x), (acos x)
(atan y), (atan y x)
The second form uses both signs to find the quadrant.
(sinh x), (cosh x), (tanh x)
(asinh x), (acosh x), (atanh x)
acosh is undefined below 1, atanh outside -1 to 1.
(radians degrees), (degrees radians)
Conversions.
Construction and conversion
Form
Meaning
(vec2 ...), (vec3 ...), (vec4 ...) and the ivec, uvec, bvec, dvec kinds
A vector from its components, given as scalars and vectors in order, or from one scalar for every component. Components are converted to the vector's type.
(mat2 ...) … (mat4x3 ...) and the dmat kinds
A matrix from its components in column-major order, given as scalars and vectors; or one scalar for the diagonal; or a matrix to resize.
(float x [prototype])
x as a :float, or a :double kept as it is; with a prototype such as 1d0, of the prototype's type.
(int x)
x as an :int, truncating a float.
(uint x)
x as a :uint.
(bool x)
x as a :bool, true if it is not zero.
(double x)
x as a :double.
(vector element ...)
An array of the elements, all of one type. Integer literals fit the others.
(make-array length :initial-element value)
An array of length, written in the code, of copies of value.
(make-name :slot value ...)
A struct, from a value for every slot. Defined by define-struct.
Components and elements
Form
Meaning
(x v), (y v), (z v), (w v)
A component of a vector. A place.
(swizzle v :components)
A vector of the named components, in order, such as (swizzle v :zyx). Components are x, y, z and w. A place if none repeats.
(aref object i)
Component i of a vector, column i of a matrix, or element i of an array. A place.
(length object)
The number of elements of an array, an :int; the Euclidean length of a vector; the absolute value of a :float.
(name-slot struct)
A struct's slot. Defined by define-struct. A place.
(slot-value struct 'slot)
The same, by slot name. A place.
(with-slots (slot-entry ...) struct body ...)
Each entry, slot or (var slot), names the struct's slot, to read and assign.
Geometry
Form
Meaning
(dot a b)
Dot product.
(cross a b)
Cross product of two :vec3s.
(length v)
Euclidean length.
(distance a b)
Distance between two points.
(normalize v)
v scaled to length 1. Undefined for a zero vector.
(reflect incident normal)
incident reflected about the plane with the unit normal.
(refract incident normal eta)
The unit incident refracted through the surface with the unit normal, for the ratio of indices eta. A zero vector on total internal reflection.
(face-forward n i reference)
n if (dot reference i) is negative, else (- n).
Interpolation
Form
Meaning
(mix a b s)
a × (1 - s) + b × s, per component. With a :bools, b where it is true and a elsewhere, which also picks between ints, uints and bools.
(clamp x low high)
x limited to low…high, per component.
(step edge x)
0.0 where x is below edge, 1.0 elsewhere, per component.
A complex number: a :dcomplex if either part is a :double, else a :complex.
(realpart z), (imagpart z)
Parts. Of a real number, itself and 0.
(conjugate z)
The imaginary part negated.
(phase z)
The angle in the complex plane, -π to π. Not of a :dcomplex.
(cis angle)
(complex (cos angle) (sin angle)).
(rational i)
An integer as a :ratio.
(numerator r), (denominator r)
Parts of a ratio in lowest terms; of an integer, itself and 1.
+ - * / = /= zerop abs take complex numbers, and exp log sqrt expt sin cos tan take a :complex. Ratios take arithmetic, comparisons, abs, signum, floor and its kin, and float.
Bits
On :ints and :uints, per component unless noted.
Form
Meaning
(logand a b ...), (logior a b ...), (logxor a b ...)
And, inclusive or, exclusive or.
(lognot a)
Complement.
(logeqv a b), (lognand a b), (lognor a b)
Exclusive nor; not and; not or.
(logandc1 a b), (logandc2 a b), (logorc1 a b), (logorc2 a b)
With the complement of the first or second.
(logtest a b)
True if they have a set bit in common. Scalars.
(logbitp index integer)
True if bit index is set. Scalars.
(ash integer count)
Shift left by count, or right by -count. An :int shifts right with its sign, as cl:ash does. A shift of 32 or more is undefined.
(byte size position)
The bits ldb and dpb take. Appears only in their forms.
(ldb (byte size position) integer)
Those bits, as a non-negative integer of its type.
(dpb new (byte size position) integer)
integer with those bits replaced by the low bits of new.
(logcount x)
The number of set bits, an :int. An :int counts its set bits in two's complement, where cl:logcount counts a negative integer's zero bits.
(integer-length x)
The bits x needs beyond its sign, as cl:integer-length.
(find-lsb x), (find-msb x)
Index of the lowest, or highest, set bit, or -1. find-msb of a negative :int finds the highest clear bit.
(bitfield-reverse x)
The bits in reverse order.
(add-carry a b)
The :uint sum wrapped to 32 bits, and 1 if it carried, as two values.
(subtract-borrow a b)
The :uint difference wrapped to 32 bits, and 1 if it borrowed, as two values.
(multiply-extended a b)
The 64-bit product of two :ints or two :uints, as its high and low 32 bits.
Floats and packing
Form
Meaning
(float-bits x)
The bits of a float as a :uint, per component. (int (float-bits x)) gives them as an :int.
(float-from-bits bits)
The float with those bits, per component.
(float-sign float [magnitude])
magnitude's absolute value, 1.0 by default, with the sign of float, which may be -0.0.
(decode-float x)
The significand from 0.5 to 1, the exponent as an :int, and the sign, as three values.