API Reference

Every exported symbol of clsl, clsl/vulkan and clsl/gmath, by package. The docstrings say more, and shader-documentation describes each name of the language. The IR and SPIR-V Reference lists the other packages.

clsl

Definitions

Symbol	Kind	What it is
define-shader name stage parameters &body body	macro	Define a shader, a stage of a program: a function from its inputs to its outputs. See Definitions and Stages.
define-function name parameters &body body	macro	Define a shader function, which shader code calls.
define-struct name &body slots	macro	Define a struct, with its constructor, copier and accessors, as defstruct does.
define-macro name lambda-list &body body	macro	Define a shader macro, as defmacro defines a macro.
define-type-alias name type &optional documentation	macro	Define another name of a type.
define-uniform name type &key value group documentation metadata	macro	Define a special variable that shader code reads as a uniform. See Uniforms and Resources.
define-program name &body stages	macro	Define a program of stages, checked against each other. See Programs.
&uniform	symbol	In a shader's parameter list, starts its uniforms.
&shared	symbol	In a compute shader's parameter list, starts the variables its workgroup shares.
derivative-uniformity	declaration	(declare (derivative-uniformity :error, :warning or :off)): what becomes of a derivative where control flow may not be uniform. See Uniform Control Flow.
remove-definition name	function	Remove the definition of any kind named name, and return true if there was one.
definitions-generation	function	A number that grows whenever a definition is made, redefined or removed. Allocates nothing.
shader-documentation name	function	The documentation of a name in shader code: a definition, an operator of the language, a type, shader-type, &uniform or &shared.

Programs

Symbol	Kind	What it is
program	structure	A program compiled for a target. It never changes, and may be shared between threads.
compile-program program &key target	function	Compile a program, by its name or its stages, for a target, such as :vulkan, and return the program: the one compiled before, while the definitions it was compiled from are as they were.
recompile-program program	function	Compile a program again, from the definitions as they are now, for its target.
program-stale-p program	function	True if a definition the program was compiled from has been redefined or removed since. Allocates nothing.
forget-compiled-programs	function	Forget the programs compile-program keeps, so that the next calls compile afresh.
program-target program	function	The name of the target it was compiled for.
program-stages program	function	Its stages, in the order they run.
program-shader-name program stage	function	The name of its shader of a stage, or nil.
program-spirv program stage	function	A stage's SPIR-V, a vector of 32-bit words, the program's own.
program-ir program stage	function	The IR a stage became, in its external form.
disassemble-program program stage &key stream	function	Print a stage's code as its target prints it: SPIR-V assembly for :vulkan.
program-workgroup-size program	function	Its compute shader's workgroup size, three counts, or nil.
program-patch-size program	function	How many vertices each patch has, or nil without tessellation.
program-features program	function	The optional device features it needs, named as cl-gfx's device-features names them.
program-vertex-inputs program	function	Its vertex shader's inputs, as vertex-inputs.
program-vertex-buffers program &key step	function	The layout of one vertex buffer that feeds every input, as cl-gfx's create-render-pipeline takes :vertex-buffers.
vertex-input	structure	An input of a vertex shader.
vertex-input-name, vertex-input-location, vertex-input-type, vertex-input-formats input	functions	Its name, its first location, its type, and the formats of the vertex attributes it is read from, one for each location, in cl-gfx's names.
program-uniforms program	function	The members of its uniform blocks, as uniforms, :frame's first.
uniform	structure	A member of a uniform block.
uniform-name, uniform-type, uniform-group, uniform-offset uniform	functions	Its name, type, group, and offset in its group's block, laid out by std140. uniform-group is a type too.
uniform-documentation, uniform-metadata uniform	functions	What define-uniform gave it, or nil.
program-uniform-block-size program group	function	The size in bytes of a group's uniform block, or 0.
program-resources program &key kind	function	Its textures, storage buffers and storage images, or those of a kind, as resources.
resource	structure	A uniform that is a binding of its own: a texture, a storage buffer or a storage image.
resource-name, resource-type, resource-group, resource-binding resource	functions	Its name, type, group, and binding in the group's bind group.
resource-kind, resource-access, resource-format resource	functions	:texture, :storage-buffer or :image; a storage buffer's or image's access, or nil; a storage image's format, or nil.
program-bindings program	function	Every binding of every group, as program-bindings.
program-binding	structure	A binding a program's uniforms need.
program-binding-group, program-binding-number, program-binding-kind, program-binding-stages binding	functions	Its group, its number in the group's bind group, its kind, :uniform-block, :storage-buffer, :read-only-storage-buffer or a texture's or image's type, and the stages that use it.
program-layout-entries program	function	For each bind group, by index from 0, the entries of its layout, as cl-gfx's create-bind-group-layout takes them.

Packing and layout

Symbol	Kind	What it is
pack-uniforms program group &key values buffer	function	Write a group's uniform block into buffer, or a new vector of bytes, and return it. values may also give other groups' uniforms, which this block leaves for theirs; a name that is no uniform of the program's blocks is an error. Given a buffer, allocates nothing.
pack-value type value buffer &key offset layout	function	Write one Lisp value of a type into a vector of bytes, by std140 or std430, and return the vector.
dfloat-parts number	function	The float pair nearest a real, as two single-floats, as a :dfloat holds it.
layout	type	:std140, a uniform block's layout, or :std430, a storage buffer's.
layout-size type &key layout	function	The size in bytes of a value of a type.
layout-alignment type &key layout	function	The alignment in bytes of a value of a type.
array-stride type &key layout	function	The bytes from one element of an array to the next.
struct-layout name &key layout	function	The slots of a struct laid out, as slot-layouts, and its size.
slot-layout	structure	A slot of a struct as a layout lays it out.
slot-layout-name, slot-layout-type, slot-layout-offset slot	functions	Its name, its type, and its offset in bytes from the struct's start.

See Uniforms and Resources.

Types

Symbol	Kind	What it is
shader-type	type	A type of clsl's language, written as a keyword, a name or a list. (shader-documentation 'shader-type) lists them.
stage	type	A stage of a program: :vertex, :tessellation-control, :tessellation-evaluation, :geometry, :fragment or :compute.
uniform-group	type	:frame, :material or :draw. Also the reader of a uniform's group.
uniform-group-index group	function	The bind group of a group: 0, 1 or 2.
texture-type-p type	function	True for a texture type, such as :sampler2d.
image-type-p type	function	True for a storage image type, such as :image2d.
texture-type-shape type	function	The shape of the texture a GPU layer binds, in cl-gfx's dimensions or :buffer; whether it is multisampled; whether it holds depths.

Conditions

Symbol	Kind	What it is
clsl-error	condition	The base of every error clsl signals.
clsl-error-message condition	function	What went wrong, and what to do about it.
shader-error	condition	Shader code clsl refuses, or stages that do not fit together.
shader-error-definition, shader-error-form condition	functions	The definition at fault, and the form.
undefined-shader-function	condition	A call of a function no one defined, when a program is compiled.
undefined-shader-function-name condition	function	The function's name.
forward-reference-warning	condition	A style warning: a definition calls a shader function not defined yet.
forward-reference-warning-definition, forward-reference-warning-name condition	functions	The definition that calls it, and its name.
program-warning	condition	A warning: a redefinition after which a program no longer compiles.
program-warning-program, program-warning-error condition	functions	The program, and the error compiling it would signal.
uniformity-warning	condition	A warning: a derivative, declared a warning, may run where control flow is not uniform.
uniformity-warning-definition, uniformity-warning-form, uniformity-warning-message condition	functions	The definition, the form, and why control flow may not be uniform there.
no-target-error	condition	The target asked for is not loaded.
no-target-error-target condition	function	The target's name.
unsupported-error	condition	The target cannot express what a shader asks for.
unsupported-error-feature, unsupported-error-form condition	functions	What the target lacks, and the form that needs it, or nil.
internal-error	condition	clsl made invalid IR or SPIR-V of shaders it had accepted: a bug in clsl.
internal-error-ir condition	function	The external form of the IR it was compiling, for the report.

See Errors.

The language

These name the language's own forms in shader code, and have no meaning in Lisp. Language Functions describes them.

Symbols	What they are
vec2, vec3, vec4	vectors of :float values
dvec2, dvec3, dvec4	vectors of :double values
ivec2, ivec3, ivec4	vectors of :int values
uvec2, uvec3, uvec4	vectors of :uint values
bvec2, bvec3, bvec4	vectors of :bool values
mat2, mat3, mat4, mat2x3, mat2x4, mat3x2, mat3x4, mat4x2, mat4x3	matrices of floats, of columns of components
dmat2, dmat3, dmat4, dmat2x3, dmat2x4, dmat3x2, dmat3x4, dmat4x2, dmat4x3	matrices of doubles
int, uint	an integer's bits as an :int or a :uint
dfloat	a number as a float pair
dfvec2, dfvec3, dfvec4	vectors of float pairs
x, y, z, w	a vector's first to fourth component, a place
swizzle	the components a keyword names, a place
inverse-sqrt, fma	1 over a square root; a product and a sum rounded once where the GPU fuses them
mix, clamp, smoothstep	blending, clamping and the smooth step
radians, degrees	an angle in radians, or in degrees
dot, cross, norm, distance, normalize	the dot and cross products, the Euclidean length and distance, and a vector of length 1
reflect, refract, face-forward	the directions of reflection and refraction, and a normal facing a direction
transpose, determinant, inverse, outer-product, matrix-component-product	the functions of matrices
float-bits, float-from-bits	a :float's 32 bits, and the :float of 32 bits
float-nan-p, float-infinity-p	true for a NaN, or an infinity
add-carry, subtract-borrow, multiply-extended	a sum and its carry, a difference and its borrow, a product's low and high bits
find-lsb, bitfield-reverse	the lowest 1 bit's position, and the bits in reverse order
pack-unorm-4x8, pack-snorm-4x8, pack-unorm-2x16, pack-snorm-2x16, pack-half-2x16	floats packed into a :uint
unpack-unorm-4x8, unpack-snorm-4x8, unpack-unorm-2x16, unpack-snorm-2x16, unpack-half-2x16	the floats of a :uint
pack-double-2x32, unpack-double-2x32	a :double of two words, and its two words
sample, fetch, gather	a texture's texels, through its sampler, as they are, and a component of four. See Uniforms and Resources
texture-size, texture-levels, texture-samples, texture-query-lod	a texture's size, mip levels, samples and level of detail
image-load, image-store, image-size, image-samples	a storage image's texels, its size and samples
atomic-incf, atomic-decf, atomic-min, atomic-max	atomics of an integer place. See Shared Memory and Atomics
atomic-logand, atomic-logior, atomic-logxor, atomic-exchange, compare-and-swap	the other atomics
barrier	waits for every invocation of the workgroup
memory-barrier, memory-barrier-buffer, memory-barrier-image, memory-barrier-shared, group-memory-barrier	the memory barriers
dfdx, dfdy, fwidth, dfdx-fine, dfdy-fine, fwidth-fine, dfdx-coarse, dfdy-coarse, fwidth-coarse	derivatives across the quad. See Uniform Control Flow
interpolate-at-centroid, interpolate-at-sample, interpolate-at-offset	a fragment shader's input interpolated elsewhere
discard	makes the fragment draw nowhere
vertex-index, instance-index	a vertex shader's built-in inputs
invocation-id, primitive-id, tessellation-coord, input-position	the built-in inputs of tessellation and geometry shaders, and of fragment shaders for primitive-id
fragment-coord, front-facing-p, helper-invocation-p, point-coord, sample-index, sample-position	a fragment shader's built-in inputs
global-invocation-id, local-invocation-id, local-invocation-index, workgroup-id, workgroup-count, workgroup-size	a compute shader's built-in inputs
set-tessellation-levels	a tessellation control shader's levels
emit-vertex, end-primitive	a geometry shader's vertices and strips

See Definitions and Stages for the built-in inputs and stage functions.

clsl/vulkan

Symbol	Kind	What it is
vulkan-target	class	The :vulkan target: SPIR-V 1.6 and the memory model Logical GLSL450, as glslang makes them for Vulkan 1.4. For back ends and tests; programs name the target :vulkan. See Targets.

clsl/gmath

Exports nothing. Loading clsl/gmath makes cl-gmath's types type aliases and its functions shader functions and shader macros: see Systems.