Getting Started

Requirements

• A Lisp: SBCL.
• Vulkan 1.4, whose drivers have every feature cl-gfx enables on all devices. Any current GPU driver has it. Mesa's lavapipe (llvmpipe) is a software renderer that works without a GPU, and the tests use it.
• SPIR-V shaders: cl-gfx takes compiled shaders. glslangValidator -V or glslc compiles GLSL into SPIR-V. clsl writes shaders in Lisp and compiles them to SPIR-V itself.
• For windows: cl-windowing, which supports Wayland and Windows, and later X11.

On Debian or Ubuntu:

apt install mesa-vulkan-drivers vulkan-validationlayers glslang-tools

vulkan-validationlayers is optional, but you want it while developing. See Errors and Validation.

Systems

cl-gfx is split into several ASDF systems:

System	What it is	Depends on
cl-gfx	The API. It knows nothing about windows or graphics APIs.	cl-ffi
cl-gfx/vulkan	The Vulkan backend, registered as :vulkan.	cl-gfx, cl-vk
cl-gfx/windowing	Lets you draw into cl-windowing's windows.	cl-gfx, cl-gfx/vulkan, cl-windowing
cl-gfx/test	The Parachute test suite.	all of the above, parachute, and cl-windowing/wayland where Wayland is

Load a backend, or open-device signals no-backend-error; it opens a device through :vulkan unless asked for another:

(asdf:load-system :cl-gfx/vulkan)             ; offscreen rendering and compute
(asdf:load-system :cl-gfx/windowing)          ; also loads cl-gfx/vulkan
(asdf:load-system :cl-windowing/wayland)      ; a window system to present to:
                                              ; :cl-windowing/win32 on Windows

Packages

Package	Use
cl-gfx	Everything a program uses. The examples in this wiki use the nickname gfx.
cl-gfx/backend	The protocol backends implement. Programs don't need it. See Backend Protocol.
cl-gfx/vulkan	Exports only the Vulkan side of the surface target protocol.
cl-gfx/windowing	Exports nothing. Loading it is enough.

A typical package definition:

(defpackage #:my-game
  (:use #:cl)
  (:local-nicknames (#:gfx #:cl-gfx) (#:win #:cl-windowing)))

Dependencies

Dependencies are pinned in the stiftfile with stift, which fetches them when a command needs them.

Running the tests

cd cl-gfx
stift test

asdf:test-system signals an error if any test fails, so the command exits unsuccessfully.

The tests render offscreen on whatever Vulkan driver is present (lavapipe in CI), and, where Wayland is, present to a headless Weston; on Windows, the tests that need Weston are not loaded. On Linux they need:

apt install mesa-vulkan-drivers weston vulkan-validationlayers

When the validation layer is installed, every test device runs under it, synchronization checks included, and the tests check that it reported no errors.

Next

Read Concepts, then follow Devices and Frames.