API Reference

Every exported Lisp function, macro, type and condition of the cl-gsl package, the Lisp side of the library. The operators used inside shader code are in Operator Reference.

Every function here has a docstring; (documentation 'name 'function) gives it at the REPL.

Defining

define-function macro

(define-function name ((param type) ...) [docstring] body ...)

Defines the shader function name. The body's last form gives the value, whose type is inferred, or several with values. Checked at once; on an error the previous definition stays. Calling a function not defined yet warns forward-reference-warning. See Shader Code.

define-shader macro

(define-shader name stage (input ... &uniform uniform ... &shared shared ...) [docstring] body ...)

Defines the shader stage name. stage is :vertex, :fragment, or a list for the stages with options:

(:compute :workgroup-size (x [y [z]]))
(:tessellation-control :patch-size n :vertices n)
(:tessellation-evaluation :patch-size n [:domain d :spacing s :winding w :point-mode b])
(:geometry :input primitive :output primitive :max-vertices n [:invocations n])

• Inputs: (name type &key location) for a vertex shader, (name type &key interpolation) for a fragment shader, (name type) for the others.
• Uniforms: (name type &key group storage format access).
• Shared variables, compute only: (name type).

&uniform and &shared are cl-gsl's exported symbols. In a package that uses cl-gsl they need no prefix; elsewhere write them through a nickname, as gsl:&uniform.

See Stages and Uniforms and Resources.

define-struct macro

(define-struct name [docstring] (slot type) ...)

Defines a struct for shader code, with a constructor make-name taking every slot by keyword and an accessor name-slot per slot, interned in the current package. See Structs.

define-variable macro

(define-variable name type &key value group documentation)

Defines name as a special variable, as defvar does, and as a uniform of type in group (:material by default) that any shader code may read. pack-uniforms fills it from the variable's value. See Uniforms and Resources.

define-macro macro

(define-macro name lambda-list [docstring] body ...)

Defines a shader macro, as defmacro defines a Lisp macro. See Extending Shader Code.

define-type-alias macro

(define-type-alias alias type)

Makes the symbol alias another name for the shader type type.

remove-definition function

(remove-definition name) → boolean

Forgets the shader function, stage, struct or shader variable name; a shader variable's Lisp variable stays. Returns true if there was one.

shader-documentation function

(shader-documentation name) → (or string null)

The documentation of name in shader code: a function, stage, struct, shader variable, struct constructor or accessor, built-in operator, or shader-type, which lists every type.

Compiling and programs

compile-program function

(compile-program &key vertex tessellation-control tessellation-evaluation geometry fragment compute)
  → program

Checks, translates and compiles the named shaders into a program. Signals shader-error for mistakes in shader code and gsl-error for stages that do not go together. See Programs.

program type

The stages of a compiled shader program. Never changes once compiled; may be shared between threads.

Program queries

Function	Returns
(program-stages program)	List of stage keywords.
(program-shader-name program stage)	The shader's name, or nil.
(program-spirv program stage)	(simple-array (unsigned-byte 32) (*)), SPIR-V for Vulkan 1.3.
(program-glsl program stage)	The Vulkan GLSL it was compiled from.
(program-vertex-inputs program)	A list of vertex-inputs.
(program-patch-size program)	Vertices per patch, or nil.
(program-workgroup-size program)	(x y z), or nil.
(program-uniforms program)	A list of uniforms, the members of the groups' uniform blocks.
(program-uniform-block-size program group)	Bytes, or 0.
(program-resources program &key kind)	A list of resources: textures, storage buffers and storage images, or those of kind, :texture, :storage-buffer or :image.
(program-bindings program)	A list of program-bindings, by set.

program-spirv and program-glsl signal gsl-error for a stage the program does not have.

What the queries return

Each is a structure that never changes. More readers may come; none will go.

Structure	Readers
vertex-input	vertex-input-name, vertex-input-location, vertex-input-type
uniform	uniform-name, uniform-type, uniform-group, uniform-offset (bytes into the group's block)
resource	resource-name, resource-type, resource-group, resource-binding, resource-kind (:texture, :storage-buffer or :image), resource-access (:read, :write or :read-write; nil for a texture), resource-format (an image's format; nil otherwise)
program-binding	program-binding-group, program-binding-set, program-binding-number, program-binding-kind, program-binding-stages

A binding's kind is :uniform-block, :storage-buffer, :read-only-storage-buffer, or a texture's or image's type. See Programs.

Following redefinitions

Function	Returns
(definitions-generation)	A non-negative integer that grows whenever a definition changes. Allocates nothing.
(program-stale-p program)	True if something the program was compiled from has changed since. Allocates nothing.
(recompile-program program)	A new program, compiled from the current definitions of the same shaders.

Uniform data

pack-uniforms function

(pack-uniforms program group &key values buffer) → buffer

Writes program's uniform block of group into buffer, a vector of (unsigned-byte 8) at least program-uniform-block-size long, or a fresh one. Shader variables come from their Lisp variables, other uniforms from values, a plist of the uniforms' names as keywords and their values, such as (:tint #(1 0.5 0.5 1)). Given a buffer, allocates nothing.

pack-value function

(pack-value type value buffer &key (offset 0) (rules :std140)) → buffer

Writes the Lisp value of the shader type into buffer at offset, by rules. Allocates nothing. See Uniforms and Resources for how each type is given.

Layout

Function	Returns
(layout-size type &key (rules :std140))	Size in bytes.
(layout-alignment type &key (rules :std140))	Alignment in bytes.
(array-stride type &key (rules :std140))	Bytes between array elements.
(struct-layout name &key (rules :std140))	((slot type offset) ...), then the struct's size.

uniform-group-index function

(uniform-group-index group) → (integer 0 2)

The bind group of group: 0 for :frame, 1 for :material, 2 for :draw.

Types

Type	What it is
shader-type	A type in shader code. See Types.
stage	(member :vertex :tessellation-control :tessellation-evaluation :geometry :fragment :compute)
uniform-group	(member :frame :material :draw). Also the reader of a uniform's group.
layout-rules	(member :std140 :std430)

Function	Returns
(texture-type-p type)	True for a texture type such as :sampler2d.
(image-type-p type)	True for a storage image type such as :image2d.
(texture-type-shape type)	For a texture or image type: the shape (:1d :1d-array :2d :2d-array :3d :cube :cube-array :buffer), whether it is multisampled, and whether it is a shadow texture, as three values.

Conditions

Condition	Parent	Readers
gsl-error	error	gsl-error-message
shader-error	gsl-error	shader-error-definition, shader-error-form
undefined-shader-function	shader-error	undefined-shader-function-name
glslang-error	gsl-error	glslang-error-log, glslang-error-glsl
forward-reference-warning	style-warning	forward-reference-warning-definition, forward-reference-warning-name

See Errors and Threads.