Deviations from Vulkan

gfx-hal is modeled after Vulkan API. For the most part, one can find an answer to an API question by just reading the Vulkan spec. There are, however, important differences that we list here:

Iterators

It's idiomatic in Rust to work with iterators and borrowing. All of our function signatures that work with arrays/lists of data are therefore accepting generic iterators instead of slices. Sometimes, it makes the signatures hard to read, but that allows us to have less overhead when called from higher-level libraries, which typically have their own (bigger) objects corresponding to GPU primitives.

Handles

All the GPU primitives we expose are opaque, non-cloneable objects compared to Vulkan's handles. If users need to share them between threads, they need to use the regular Rust means to do so: Arc, Mutex, etc. Exposing the objects this way allows us to rely more on the mutability (as in "&mut self") and Sync features of the language. Destruction methods take ownership of the primitives.

Some Vulkan Portable limitations

For example, TRIANGLE_FAN primitive topology is missing. These are in process of being specified by Vulkan Portability Initiative of Khronos, which we are a part of.

Unsound pieces

• the clear color list provided for a render pass: We expect a value per attachment that is cleared, while Vulkan expects just a value per attachment (but not necessarily as many values as there are attachments, d'oh).

Convenience pieces

• descriptor inside a DescriptorSetWrite don't have to be of the same type and shader stages.

Swapchain

We have a simplified swapchain API given that "VK_swapchain_KHR" is extremely tricky to map properly to other platforms. In our current API, you can only render into swapchain, and nothing else.