API Reference

Every exported symbol of the package cl-vk, by topic. Every function declares the types of its arguments and results, which SBCL checks on entry: a wrong argument signals a type-error, and a constant of the wrong type in a call is a warning when the call is compiled. Objects are structs: they print readably for debugging, and their readers are listed with them. Examples use the nicknames vk for cl-vk, vks for cl-vk/structs and vk-ffi for cl-vk/ffi.

• Types
• Conditions
• Results
• Handles and command tables
• Instances
• Debug messages
• Physical devices
• Devices and queues
• Fences and semaphores
• Surfaces
• Swapchains
• Structs
• Definitions used by generated code

The raw layer has its own page, Raw FFI Layer, and the generator its own, Generator and Registry.

Types

version type

A Vulkan version as a list (MAJOR MINOR) or (MAJOR MINOR PATCH), each part in the range Vulkan packs it in: MAJOR below 128, MINOR below 1024 and PATCH below 4096.

extent type

A size in pixels, as a list (WIDTH HEIGHT) of 32-bit unsigned integers.

object type

The base of cl-vk's objects that wrap a Vulkan handle: instances, physical devices, devices, queues, surfaces, swapchains, fences and binary semaphores. raw-handle takes any of them.

validation-check type

A check the validation layer makes only when asked: :synchronization or :best-practices. See create-instance.

nanoseconds type

A duration in nanoseconds, as Vulkan's timeouts take it: (unsigned-byte 64).

+forever+ constant

The timeout that waits forever, the largest nanoseconds.

Conditions

See Errors for when each is signalled and what to do.

vk-error condition

The base of every error cl-vk signals. Subtype of error.

result-error condition

A Vulkan command reported failure. Subtype of vk-error.

• result-error-result → keyword: the VkResult, a vks:result such as :error-out-of-device-memory, or an integer for a code newer than the bindings.
• result-error-command → string: the command, such as "vkQueueSubmit2".

out-of-date-error condition

A swapchain no longer matches its surface. Recreate the swapchain. Subtype of result-error.

surface-lost-error condition

A surface is no longer usable, as after its window was destroyed. Destroy its swapchains and the surface. Subtype of result-error.

device-lost-error condition

A device was lost, through a driver error, a GPU reset or a hang. Destroy everything made from the device, and the device. Subtype of result-error.

unsupported-error condition

An instance, device or swapchain was asked for something the system does not support. Signalled before Vulkan is called, so nothing was created. Subtype of vk-error.

• unsupported-error-message → string: what was asked for, what is missing, and what to do.
• unsupported-error-missing → list: the names of what is missing.

struct-value-error condition

A struct field was given a value it cannot hold. Subtype of vk-error.

• struct-value-error-struct → symbol: the struct, a symbol of cl-vk/structs.
• struct-value-error-field → keyword: the field.
• struct-value-error-value: the value given.
• struct-value-error-expected → string: what the field takes, in words.

destroyed-object-error condition

A destroyed object was used, or destroyed again. Subtype of vk-error.

• destroyed-object-error-object: the object.

live-children-error condition

An object was to be destroyed while objects made from it are alive. Nothing was destroyed. Subtype of vk-error.

• live-children-error-object: the object.
• live-children-error-children → list: the objects made from it that are alive.

Results

check result command → keyword or integer

Return result, a VkResult integer returned by the raw command named command (a string), as a keyword such as :success or :suboptimal-khr when it reports success, and signal a result-error (or the matching subtype) when it reports failure. Use it on the results of the raw commands of cl-vk/ffi. Allocates nothing.

(vk:check (vk-ffi:vk-end-command-buffer commands buffer) "vkEndCommandBuffer")
;; => :SUCCESS

Handles and command tables

raw-handle object → pointer or integer

Return the Vulkan handle of object, any cl-vk object: a foreign pointer for a dispatchable handle (instance, physical device, device, queue), an integer for the others (surface, swapchain, fence, semaphore). A raw handle is returned unchanged. Signals destroyed-object-error for a destroyed object, and type-error for anything that is neither an object nor a raw handle. The escape hatch to the raw layer.

instance-commands instance → vk-ffi:instance-commands

The command table of instance, for calling the raw instance-level commands of cl-vk/ffi. An escape hatch to the raw layer, as raw-handle is. Signals destroyed-object-error once the instance is destroyed.

device-commands device → vk-ffi:device-commands

The command table of device, for calling the raw device-level commands (those of the device, its queues and command buffers). Its pointers come from the driver directly. An escape hatch to the raw layer, as raw-handle is. Signals destroyed-object-error once the device is destroyed.

swapchain-images swapchain → list

The raw VkImage handles of the images of swapchain, integers in index order, as acquire-next-image and present number them. An escape hatch to the raw layer, as raw-handle is: cl-vk does not wrap images, so code that draws into them makes their views through cl-vk/ffi. The images belong to the swapchain. Signals destroyed-object-error once the swapchain is destroyed.

Instances

instance-version → list

The highest Vulkan version the installed loader supports for instances, (MAJOR MINOR PATCH).

available-layers → list

The names of the installed layers, such as "VK_LAYER_KHRONOS_validation".

available-instance-extensions &optional layer → list

The names of the instance extensions the loader and drivers provide, or those the layer named layer provides.

instance struct

A Vulkan instance. Readers: instance-api-version (the version asked for, a version (MAJOR MINOR PATCH)), instance-extensions and instance-layers (the names enabled, those validation added included), instance-commands. Thread rules: may be used from several threads; creating and destroying the objects made from it must happen on one thread at a time.

create-instance &key api-version extensions layers validation validation-checks application-name application-version engine-name engine-version → instance

Create an instance for api-version (default '(1 4)) with the extensions and layers named. When validation is true, also enable the Khronos validation layer and VK_EXT_debug_utils, and queue their messages for take-debug-messages. validation-checks, a list of validation-check, turns on checks the layer leaves out by default, and turns validation on. application-name (default ""), application-version (0), engine-name ("cl-vk") and engine-version (0) are passed on to drivers. Signals unsupported-error, before creating anything, if the loader does not support api-version or a layer or extension is missing. See Instances and Validation.

destroy-instance instance

Destroy instance and its debug messenger. Signals live-children-error if devices or surfaces made from it are alive.

with-instance (variable &rest arguments) &body body macro

Evaluate body with variable bound to (create-instance ,@arguments), and destroy the instance when body is left, unless it was destroyed already.

Debug messages

take-debug-messages instance → list

The debug-messages queued for instance since the last call, oldest first; they are forgotten. nil for an instance made without validation. May be called from any thread.

debug-message struct

A message from a validation layer or driver. Immutable. Readers:

• debug-message-severity → a vks:debug-utils-message-severity-flag-bits-ext: :verbose, :info, :warning or :error.
• debug-message-types → a list of :general, :validation and :performance.
• debug-message-text → string.
• debug-message-id-name → string or nil: the name of the check, such as "SYNC-HAZARD-WRITE-AFTER-READ".

Physical devices

physical-devices instance → list

The physical devices of instance, each a physical-device.

physical-device struct

A GPU or software renderer. Immutable, valid while its instance is; may be shared between threads. Readers:

• physical-device-instance
• physical-device-name → string
• physical-device-type → a vks:physical-device-type: :discrete-gpu, :integrated-gpu, :virtual-gpu, :cpu or :other
• physical-device-api-version → a version (MAJOR MINOR PATCH)
• physical-device-driver-version, physical-device-vendor-id, physical-device-device-id → integer
• physical-device-queue-families → list of queue-family
• physical-device-extensions → list of extension names

queue-family struct

A family of queues of a physical device. Immutable. Readers: queue-family-index, queue-family-flags (a list such as (:graphics :compute :transfer)), queue-family-count (how many queues it has), queue-family-timestamp-valid-bits.

The same symbol queue-family is also the reader of a queue's family.

find-queue-family physical-device predicate → queue-family or nil

The first queue family of physical-device for which predicate, called with the queue-family, returns true.

physical-device-feature-p physical-device struct field → boolean

True if physical-device supports the feature field (a keyword such as :dynamic-rendering) of struct (a feature struct such as vks:physical-device-vulkan13-features). Core Vulkan 1.0 features are the fields of vks:physical-device-features. Signals a vk-error if field is not a VkBool32 field of a feature struct.

Devices and queues

device struct

A Vulkan device. Readers: device-physical-device, device-queues, device-extensions, device-features (the requests it was created with), device-commands. Thread rules: may be used from several threads; creating and destroying the objects made from it must happen on one thread at a time.

create-device physical-device &key queues extensions features → device

Create a device on physical-device. queues lists the queues to make as (FAMILY COUNT), one entry per family; by default one queue of the first family that supports graphics. extensions names device extensions, such as "VK_KHR_swapchain". features lists features to enable as (STRUCT FIELD ...). Signals unsupported-error, before creating anything, if a queue, extension or feature is not supported; a type-error for a queue request that is not (FAMILY COUNT) or a feature request that is not (STRUCT FIELD ...); and a vk-error for a queue family asked for twice or a field that is not a feature.

destroy-device device

Destroy device. Signals live-children-error if swapchains, fences or semaphores made from it are alive. Wait for its work first, with device-wait-idle.

with-device (variable physical-device &rest arguments) &body body macro

Evaluate body with variable bound to (create-device physical-device ,@arguments); when body is left, wait for the device's work to finish and destroy it, unless it was destroyed already.

device-queue device &key family index → queue

Queue index (default 0) of the queue family family, an index, of device; by default the first queue the device was created with: (vk:device-queue device) is that queue, and (vk:device-queue device :family 2) the first queue of family 2. Signals a vk-error, listing the device's queues, if it has no such queue.

device-wait-idle device

Wait until all work submitted to device's queues has finished.

queue struct

A queue of a device. Valid while its device is. Readers: queue-device, queue-family (a queue-family), queue-index (within the family). Thread rules: submitting to and presenting on one queue must happen on one thread at a time.

Fences and semaphores

fence struct

A fence of a device. Thread rules: may be waited for on several threads at once; resetting or destroying it must not overlap any other use.

create-fence device &key signaled → fence

Create a fence, signaled already if signaled is true.

destroy-fence fence

Destroy fence. No pending work may still signal it.

wait-for-fence fence &key timeout → boolean

Wait until fence is signaled, for at most timeout nanoseconds (default +forever+). True if signaled, false if the wait timed out. Allocates nothing.

reset-fence fence

Make fence unsignaled. Allocates nothing.

fence-signaled-p fence → boolean

True if fence is signaled, without waiting.

binary-semaphore struct

A binary semaphore of a device. Thread rules: destroying it must not overlap any other use.

create-binary-semaphore device → binary-semaphore

Create a binary semaphore.

destroy-binary-semaphore semaphore

Destroy semaphore. No queue operation may still use it.

Surfaces

surface struct

A surface of an instance. Reader: surface-instance. Thread rules: may be queried from several threads at once; creating a swapchain for it or destroying it must not overlap any other use.

adopt-surface instance handle → surface

Return a surface for handle, a VkSurfaceKHR (a nonzero 64-bit integer) another library created for instance. It then belongs to cl-vk: destroy it with destroy-surface.

create-headless-surface instance → surface

Create a surface that presents nowhere, for tests and off-screen work. instance needs the extensions VK_KHR_surface and VK_EXT_headless_surface; otherwise signals unsupported-error.

destroy-surface surface

Destroy surface. Signals live-children-error if swapchains made for it are alive.

surface-capabilities physical-device surface → surface-capabilities

What physical-device can do with surface.

surface-capabilities struct

Immutable. Readers:

• surface-capabilities-min-image-count → integer
• surface-capabilities-max-image-count → integer or nil (no limit)
• surface-capabilities-current-extent → an extent, or nil when the swapchain decides the size
• surface-capabilities-min-extent, surface-capabilities-max-extent → an extent
• surface-capabilities-max-array-layers → integer
• surface-capabilities-supported-transforms → list of keywords
• surface-capabilities-current-transform → a vks:surface-transform-flag-bits-khr keyword, or the integer of a transform newer than the bindings
• surface-capabilities-supported-composite-alpha → list of keywords
• surface-capabilities-supported-usage → list of keywords

surface-formats physical-device surface → list

The formats physical-device can present to surface in, as (FORMAT COLOR-SPACE) keyword pairs such as (:b8g8r8a8-srgb :srgb-nonlinear).

surface-present-modes physical-device surface → list

The present modes supported, as keywords such as :fifo and :mailbox. :fifo is always among them.

surface-supported-p physical-device queue-family surface → boolean

True if the queues of the family queue-family, an index, of physical-device can present to surface.

Swapchains

swapchain struct

A swapchain. Readers: swapchain-device, swapchain-surface, swapchain-format (a vks:vk-format), swapchain-color-space (a vks:color-space-khr), swapchain-extent (an extent), swapchain-present-mode (a vks:present-mode-khr), swapchain-usage, swapchain-images (the raw VkImage handles, in index order: an escape hatch, see above). Thread rules: acquiring, presenting and destroying must happen on one thread at a time.

create-swapchain device surface &key extent format color-space present-mode image-count usage old-swapchain → swapchain

Create a swapchain of device for surface. Its size is the surface's own, or extent, an extent, for a surface that leaves the size to the swapchain, clamped to what the surface allows. format, a vks:vk-format, defaults to an sRGB format, color-space, a vks:color-space-khr, to :srgb-nonlinear, present-mode, a vks:present-mode-khr, to :fifo, image-count to one more than the surface's minimum, usage to (:color-attachment). old-swapchain is the swapchain this one replaces. device needs VK_KHR_swapchain. Signals unsupported-error, before creating anything, for anything the surface does not support, and a vk-error if the surface has no size and extent is not given.

destroy-swapchain swapchain

Destroy swapchain. Its images must no longer be in use.

recreate-swapchain swapchain &key extent → swapchain

Return a new swapchain like swapchain, for its surface's current size or extent, and destroy swapchain. Call it after acquire-next-image or present report :out-of-date or :suboptimal, once the device has finished with the old images.

acquire-next-image swapchain &key semaphore fence timeout → index, status

Acquire the next image to render to. semaphore and fence, of which at least one must be given, are signaled when it is ready. Waits at most timeout nanoseconds (default +forever+). Returns the image's index and a status: :success, :suboptimal (usable, but recreate soon), :out-of-date (recreate; index nil), :timeout or :not-ready (index nil). Signals result-error for other failures. Allocates nothing.

present queue swapchain image-index &key wait-semaphore → status

Present image image-index of swapchain on queue, after wait-semaphore is signaled if given. Returns :success, :suboptimal (presented, but recreate soon) or :out-of-date (recreate). Signals result-error for other failures. Allocates nothing.

Structs

See Structs for the values each kind of field takes.

with-structs (binding ...) &body body macro

Evaluate body with each variable bound to a struct in foreign memory, zeroed and with its sTypes set, for the extent of body. A binding is (variable name field value ...) for one struct, (variable name (field value ...) ...) for an array, or (variable (name count)) for count zeroed structs. name is a symbol of cl-vk/structs. Strings and lists are copied to foreign memory that lasts for the extent of body. Each struct is local to the thread running body.

set-struct pointer name &rest fields → pointer macro

Store fields, keywords and values, in the struct name at pointer, leaving the others as they are. Never allocates: strings and arrays must be foreign pointers, with their counts.

struct-ref pointer name field → value macro

The value of field of the struct name at pointer, as a Lisp value. setf-able, storing as set-struct does.

struct-aref pointer name index → pointer macro

A pointer to element index of the array of structs name at pointer.

allocate-struct name &key count → pointer

Foreign memory for count (default 1) structs name, zeroed and with their sTypes set. Lasts until free-struct. May be passed between threads, but not written by two at once.

free-struct pointer

Free structs made by allocate-struct.

Definitions used by generated code

These macros are exported for the generated file registry/structs.lisp. Programs do not call them.

define-enum-keywords enum &body entries macro

Record each (KEYWORD INTEGER) of entries as a keyword of the raw enum type enum. The generator writes beside each the deftype of its keywords, such as vks:present-mode-khr.

define-struct-description (name raw-name &optional kind) &body fields macro

Record the description of the struct name, a symbol of cl-vk/structs, over the cl-ffi struct raw-name: each field's keyword, slot, kind of value and properties.

define-struct-description-alias name target raw-name macro

Record name as another name for the described struct target.