On this page:
3.1 Design Considerations
3.2 What Did I Just Load?
3.3 Platform-Specific Definitions
3.3.1 X +   Rand  R
_  Visual  ID
_  Window
_  RROutput
_  Display
3.3.2 Wayland
_  wl_  display
_  wl_  surface
3.3.3 Windows
_  HANDLE
_  HINSTANCE
_  HWND
_  HMONITOR
_  DWORD
_  LPCWSTR
_  SECURITY_  ATTRIBUTES
3.3.4 XCB
_  xcb_  visualid_  t
_  xcb_  window_  t
_  xcb_  connection_  t
3.3.5 Zircon (Fuchsia OS)
_  zx_  handle_  t
3.3.6 Google Games
_  Ggp  Stream  Descriptor
_  Ggp  Frame  Token
3.4 Spec Version Procedures
VK_  MAKE_  VERSION
VK_  API_  VERSION_  1_  0
VK_  API_  VERSION_  1_  1
VK_  VERSION_  MAJOR
VK_  VERSION_  MINOR
VK_  VERSION_  PATCH
3.5 Additional Procedures
check-vk  Result
format-vulkan-spec-version
8.2

3 Unsafe Bindings

 (require vulkan/unsafe) package: vulkan

The unsafe module is exactly as the name implies. Use at your own risk.

vulkan/unsafe is just the output of ravk generate unsafe. You can generate your own copy to use Vulkan bindings according to this section without a dependency on this collection.

A copy of vulkan/unsafe provides over 2200 bindings representing all supported and deprecated Vulkan structs, unions, enumerated types, constants and functions across all platforms, extensions, and published Vulkan API verions. There are few protections against misuse. Any mistakes risk undefined behavior, race conditions, and memory leaks. Do not expect clear error messages, strong validation, or concise code.

Here you will also find platform-specific code, necessary loading calls to communicate with Vulkan, and a curated list of utilities not generated from a specification.

On instantiation, this module will attempt to load the host platform’s Vulkan library. Should this fail, the module will raise an error.

3.1 Design Considerations

Since vulkan/unsafe exposes a raw API, you can easily port a C program using Vulkan to Racket. You can also use this module to write your own abstractions in terms of ffi/unsafe, or to study established Vulkan literature while using Racket.

It is possible to write cross-platform and backwards-compatible Vulkan applications with this module, but you are responsible for detecting the platform and using APIs from the correct version.

3.2 What Did I Just Load?

When you require this module, you may assume that all Vulkan identifiers defined in the specification for the core API and all extensions are provided. I cannot document every binding by hand, but I thankfully don’t have to. The translation from C to Racket is not 1-to-1, but it is close enough where you can compare the below list of translation rules against a Vulkan specification document to know what bindings are available:

3.3 Platform-Specific Definitions

Vulkan is itself platform-agnostic, but extensions are necessary to integrate with platforms. Some identifiers are bound to interned symbols–such as _Display– because they are meant for use in _cpointer or _cpointer/null.

3.3.1 X + RandR

value

_VisualID : ctype? = _ulong

value

_Window : ctype? = _ulong

value

_RROutput : ctype? = _ulong

value

_Display : symbol? = 'Display

3.3.2 Wayland

value

_wl_display : symbol? = 'wl_display

value

_wl_surface : symbol? = 'wl_surface

3.3.3 Windows

value

_HANDLE : ctype? = (_cpointer _void)

value

_HINSTANCE : ctype? = _HANDLE

value

_HWND : ctype? = _HANDLE

value

_HMONITOR : ctype? = _HANDLE

value

_DWORD : ctype? = _ulong

value

_LPCWSTR : ctype? = (_cpointer _wchar)

value

_SECURITY_ATTRIBUTES : symbol? = 'SECURITY_ATTRIBUTES

3.3.4 XCB

value

_xcb_visualid_t : ctype? = _uint32

value

_xcb_window_t : ctype? = _uint32

value

_xcb_connection_t : symbol? = 'xcb_connection_t

3.3.5 Zircon (Fuchsia OS)

value

_zx_handle_t : ctype? = _uint32

3.3.6 Google Games

Be warned that these values are likely incorrect, and are apparently behind an NDA. Even if I knew what these were, I couldn’t publish them here. If you are the rare person who happened to sign this NDA and wish to use Racket on Google Games, you may need to use a different binding. I leave them here as void* in the hopes you can use them and to clarify that they are relevant to you.

3.4 Spec Version Procedures

Some core Vulkan signatures are implemented as C preprocessor macros that are difficult to transform directly to Racket. Chief among them are the expressions of specification versions that are relevant for runtime and operational use. Their names are preserved as they appear in C for consistency.

procedure

(VK_MAKE_VERSION major minor patch)  exact-positive-integer?

  major : exact-nonnegative-integer?
  minor : exact-nonnegative-integer?
  patch : exact-nonnegative-integer?
This is a Racket variant of the VK_MAKE_VERSION macro from vulkan.h.

Racket-specific Vulkan version values.

Extracts version numbers from a value constructed by VK_MAKE_VERSION.

3.5 Additional Procedures

procedure

(check-vkResult v who)  void?

  v : any/c
  who : symbol?
Equivalent to (error who "failed: ~a" v) if v is not a VkResult success code.

procedure

(format-vulkan-spec-version spec-version)  string?

  spec-version : exact-positive-integer?
Equivalent to:

(format "~a.~a.~a"
  (VK_VERSION_MAJOR spec-version)
  (VK_VERSION_MINOR spec-version)
  (VK_VERSION_PATCH spec-version))