examples

vulkan-examples

The examples

info

For the vulkan instance and all physical devices it dumps layer and extension properties to stdout. It also prints features and properties for all physical devices.

resize

A nice example of rendering into a window which can be resized. It uses the recycling Frame machinery from lib/ (timeline semaphores + a recycle channel for binary semaphores and command pools).

It renders a Julia set according the mouse position in the window.

The resourcet package is used to ensure resources are deallocated.

hlsl

A nicer example of rendering into a window which can be resized, the shaders are written in HLSL and compiled with the glslc tool from Shaderc.

If you don't have this tool installed then you might want to turn off the Cabal flag have-shaderc to stop this example from building.

It renders a triangle, sharing the lib/ recycling Frame infrastructure with resize, rays, triangle-sdl2, and triangle-glfw.

rays

An example of using the VK_KHR_ray_tracing_pipeline extension. Needs quite a new driver to run!

triangle-headless

This example:

• Renders a triangle to an image
• Copies the image contents to a CPU-mapped image
• Writes that image to "triangle.png"

It is a pretty minimal example of rendering something. Single-shot, no recycling Frame needed — just plain ResourceT IO with handles threaded as explicit args.

compute

This example renders an image of the Julia set at f(z) = z^2 -0.8 + 0.156i.

This rendering is performed by a compute shader writing to a buffer.

This program includes examples of:

• Buffer allocation with VulkanMemoryAllocator.
• Descriptor set creation and binding
• Compute shader dipatch
• Convenient shader creation using the Vulkan.Utils.ShaderQQ.comp QuasiQuoter

Single-shot like triangle-headless; uses plain ResourceT IO.

triangle-sdl2

This opens a window using SDL and renders a triangle.

The managed package is used for ensuring resources are deallocated.

Exit with q, escape or the window exit button.

triangle-glfw

This opens a window using GLFW and renders a triangle.

The managed package is used for ensuring resources are deallocated.

Exit with q, escape or the window exit button.

Building and Running

You'll need to have glslangValidator in $PATH when compiling as shaders are built in a QuasiQuoter.

There's a default.nix file in this directory which build and load the other packages in this repo. This is useful to get a Hoogle database with vulkan, VulkanMemoryAllocator and friends for developing examples. To use this with cabal you'll need to make a cabal.project file in this directory to stop cabal wanting to configure all the packages in this repo.

packages:
  ./

macOS

Jonathan Merritt has made an excellent video detailing how to set up everything necessary for running the examples on macOS here.

Building with Nix while not on NixOS

Vulkan and OpenGL programs have some trouble running on non-NixOS OSs when built with nix.

If you provision libvulkan.so (the Vulkan loader) with nix and you're not on NixOS, you'll have to use NixGL to run your programs. For this reason it's recommended to use the system-provided libvulkan.so. Make sure to change the package list in stack.yaml if you do this.

Running the examples with Stack on NixOS

If you run into

error: XDG_RUNTIME_DIR not set in the environment.
triangle-sdl2: SDLCallFailed {sdlExceptionCaller = "SDL.Init.init", sdlFunction = "SDL_Init", sdlExceptionError = "No available video device"}

It's because the pure shell instantiated by stack --nix doesn't include the XDG_RUNTIME_DIR variable which is necessary to find the vulkan ICD files. To fix this pass the --no-nix-pure flag to stack thusly:

stack --system-ghc --nix --no-nix-pure run triangle-sdl2

Running the examples with SwiftShader

Note that not all of the examples run under SwiftShader.

# This will set VK_ICD_FILENAMES to the swiftshader ICD
# It will also enable the timeline-semaphore emulation layer as swiftshader
# lacks support
nix-shell --arg withSwiftshader true
cabal run hlsl

Troubleshooting

For the examples using SDL (resize, triangle-sdl2):

• If SDL is unable to find libvulkan.so, you can set either LD_LIBRARY_PATH or SDL_VULKAN_LIBRARY, it must find the same libvulkan.so that the triangle-sdl2 binary was compiled against.

• If you run into the exception DLCallFailed {sdlExceptionCaller = "SDL.Video.Vulkan.vkLoadLibrary", sdlFunction = "SDL_Vulkan_LoadLibrary", sdlExceptionError = "Installed Vulkan doesn't implement the VK_KHR_surface extension"} it might be because the vulkan loader is unable to find the driver. To check if this is the case you can set VK_ICD_FILENAMES to the icd json file of your desired driver.