cl-vk

Vulkan for Common Lisp. cl-vk is generated from the Vulkan API registry and has two layers: a complete raw layer, one Lisp function per Vulkan command, and an idiomatic layer over it that returns Lisp values, turns error codes into conditions and fills Vulkan structs by field name.

Vulkan 1.4 is the minimum. The bindings cover Vulkan 1.0 to 1.4 and every extension except those for platforms other than Wayland, X11 and Windows, and provisional ones. Only the Vulkan loader (libvulkan.so.1, vulkan-1.dll) is needed at run time: no C compiler and no Vulkan headers.

(asdf:load-system :cl-vk)

(defpackage #:example
  (:use #:cl)
  (:local-nicknames (#:vk #:cl-vk) (#:vks #:cl-vk/structs)))
(in-package #:example)

(vk:with-instance (instance :extensions '("VK_KHR_surface" "VK_EXT_headless_surface"))
  (let ((gpu (first (vk:physical-devices instance)))
        (surface (vk:create-headless-surface instance)))
    (unwind-protect
         (vk:with-device (device gpu :extensions '("VK_KHR_swapchain")
                                     :features '((vks:physical-device-vulkan13-features
                                                  :dynamic-rendering :synchronization2)))
           (let ((swapchain (vk:create-swapchain device surface :extent '(800 600))))
             (prog1 (list (vk:physical-device-type gpu)
                          (vk:swapchain-format swapchain)
                          (vk:swapchain-extent swapchain))
               (vk:destroy-swapchain swapchain))))
      (vk:destroy-surface surface))))
;; => (:CPU :B8G8R8A8-SRGB (800 600))   ; on Mesa's lavapipe

Pages

Start here

• Getting Started: installing, loading, and a first program.
• Concepts: the systems and packages, the two layers, how objects relate, and how C names become Lisp names.

Guides

• Instances and Validation: creating an instance, layers and extensions, and reading what the validation layer reports.
• Physical Devices and Devices: choosing a GPU, queue families, features, and creating a device and its queues.
• Surfaces and Swapchains: presenting to a window, the frame loop, and recreating a swapchain after a resize.
• Fences and Semaphores: waiting for the GPU and ordering work between queue operations.
• Structs: filling and reading any Vulkan struct by field name with with-structs, set-struct and struct-ref.
• Recipes: a complete frame loop that clears the screen, choosing a GPU, calling raw commands on cl-vk's objects, and structs reused every frame.

Reference

• API Reference: every exported symbol of cl-vk.
• Errors: the conditions cl-vk signals, and what to do about each.
• Lifetimes and Threads: what outlives what, destroying objects, which objects may be shared between threads, and allocation.
• Raw FFI Layer: cl-vk/ffi, the whole Vulkan API as a direct transcription of C.
• Generator and Registry: cl-vk/generator, the registry model, and regenerating the bindings after a registry update.
• Platforms and Testing: requirements, platforms, and running the test suite.

Systems

System	What it is
cl-vk	The library. Use this one. Loads cl-vk/ffi too.
cl-vk/ffi	The raw layer, on cl-ffi, a direct transcription of the Vulkan C API.
cl-vk/generator	Build-time tool that generates the bindings from vk.xml. Not needed to use cl-vk.
cl-vk/test	The Parachute test suite.

Packages

Package	Nickname in examples	What it holds
cl-vk	vk	The idiomatic API: objects, structs, conditions.
cl-vk/structs	vks	One symbol per Vulkan struct, naming it for the struct macros, and one per enum, the type of its keywords.
cl-vk/ffi	vk-ffi	The raw layer: commands, structs, constants, foreign types.
cl-vk/generator		The generator and its registry model.

Status

The raw layer is complete. The idiomatic layer covers structs, instances, physical devices, devices and their queues, surfaces, swapchains, fences and binary semaphores. Everything else (command buffers, memory, buffers, images, pipelines and so on) is reached through the raw layer, on cl-vk's objects; Recipes shows how.

License

MIT. The registry files in registry/ are under Apache-2.0 OR MIT, as stated in each file.