Errors and Threads

Conditions

gsl-error
├── shader-error
│   └── undefined-shader-function
└── glslang-error

forward-reference-warning   (a style-warning)

Condition	Signalled when	Readers
gsl-error	The base of every error cl-gsl signals. Also signalled directly for a program whose stages do not go together, such as a tessellation control shader without an evaluation shader, and for a Lisp value that pack-value or pack-uniforms cannot write.	gsl-error-message: what went wrong, and what to do about it.
shader-error	A mistake in shader code: a malformed definition, an unknown operator or variable, a type that does not fit, a built-in used in the wrong stage, stages that do not fit together.	shader-error-definition: the name of the function or stage, or nil. shader-error-form: the form the error is about.
undefined-shader-function	A call of a name that is neither built in nor defined, found when a program is compiled.	undefined-shader-function-name
glslang-error	glslang rejected the generated GLSL. cl-gsl checks shader code before generating GLSL, so this is a bug in cl-gsl, or the result of glsl written by hand.	glslang-error-log: glslang's report. glslang-error-glsl: the GLSL.
forward-reference-warning	A style-warning, when a definition calls a function not defined yet. The definition is kept and checked again when a program that uses it is compiled.	forward-reference-warning-definition, forward-reference-warning-name

What errors look like

A shader-error's message names the definition and the form, and says what would fit:

In BROKEN: + cannot take arguments of the types :VEC3, :VEC2.  It takes
  two scalars or two vectors of the same type, which work per component;
  a scalar and a vector, or a vector and a scalar, of the same component type;
  two matrices of the same type, or a matrix and a :FLOAT;
  for *, also a matrix and a vector, or a vector and a matrix, or two matrices,
  whose sizes agree, for the linear algebra product.
  in: (+ V (VEC2 1))

In UA: K is a uniform, which shader code reads but cannot assign.  Bind its
value to a variable with LET and assign that.
  in: K

In TV: A :SAMPLER2D cannot be stored in a variable or computed with.  Pass it
straight to the operators that read it, such as SAMPLE and FETCH, or to a
shader function.
  in: S

In REC: REC calls itself, directly or through other functions.  Shader
functions cannot be recursive.

Errors keep what worked

A definition that fails its check is never stored. The previous definition stays, and so do the programs compiled from it. A mistake at the REPL never breaks what is being drawn; fix it and evaluate the definition again.

recompile-program signals the same errors as compile-program and leaves the old program as it was. See Programs for a frame loop that keeps the old program when a recompile fails.

Threads

Object	Rules
Definitions	May be made, redefined and removed from any thread. They are kept in tables behind a lock.
compile-program, recompile-program	May be called from any thread. Compiling serialises its use of glslang.
program	Never changes once compiled, so it may be shared between threads freely.
definitions-generation, program-stale-p	Safe from any thread, and allocate nothing.
pack-uniforms, pack-value	Write only into the buffer they are given. Two threads may pack at once into different buffers. Shader variables are read from the calling thread's dynamic bindings.