Dvk is a library providing bindings to Vulkan API. Unlike many other alternatives Dvk loads all Vulkan commands dynamically at run time, making compilation much more straightforward, to the point that you don't even need Vulkan to be installed to compile it. 

This library is designed following the principle of minimum surprise, it deviates very little from the official headers and does not needlessly pollute official Vulkan namespace.  There are only a handful of places where either language differences or the requirment to load dynamically had forced design to deviate from canonical, all such peculiarities are thoroughly documented on this page. Regular Khronos documentation should be sufficient to learn about all the types and functions provided by this library. 

NOTE: In current version only *khr_win32_surface* is complete out of all platform-specific WSI extensions.

## Documentation

https://www.khronos.org/registry/vulkan/specs/1.0-wsi_extensions/xhtml/vkspec.html

## Organization
All definitions are orginized into modules, the main one is *core*, the rest *khr_surface*, *ext_debug_report*, *khr_display*, *khr_display_swapchain*, *khr_swapchain*, *khr_win32_surface* are all extensions. This library does not export any ready-to-use command prototypes. All definitions are in the same order as in *vulkan.h* header file.

## Changes to official API

### Types
* ```VkClearValueUnion```
* ```VkClearColorValueUnion ```
* ```VkCoreCommands```
* ```VkKhrSurfaceCommands```
* ```VkKhrSwapchainCommands```
* ```VkKhrDisplayCommands```
* ```VkKhrDisplaySwapchainCommands```
* ```VkKhrWin32SurfaceCommands```
* ```VkExtDebugReportCommands```
* No separate ```*FlagBits``` and ```*Flags``` types just ```*Flags```
* ```VkDescriptorPoolSize.type``` is renamed to ```dType``` due to naming collision with Rust keyword ```type```
* Platform types are redefined as part of the library
* No universal VK_NULL_HANDLE constant, it's incompatible with type-safe handles

### Functions
* ```Vulkan*::new()``` and ```Vulkan*::load(&mut self, VkInstance)```
* ```::null()``` constructor and ```::is_null(&self)``` method for all handles
* From trait implementation for ```*Union``` types

## Loading

Dynamic loading has advantage over static linking in that no static library is needed to compile. Vulkan standard is fairly conservative on that point and only guarantees that a single command will be exported from the dynamic library. That command is ```vkGetInstanceProcAddr```. Once that command is acquired, it can be used to load the next tier of API consisting of three *global commands*: 

1. ```vkCreateInstance```
2. ```vkEnumerateInstanceExtensionProperties```
3. ```vkEnumerateInstanceLayerProperties```

The rest of the API, consisting of *134 core commands* can similarly be loaded with ```vkGetInstanceProcAddr```, but require a ```VkInstance``` object to load them. A ```VkInstance``` object not surprisingly can be created via global command ```vkCreateInstance```. Extension commands are loaded in exactly the same way.

This library does not export any ready-to-use command prototypes, instead you get all commands dynamically loaded and returned in structs. 

The core of Vulkan functionality resides in ```VkCoreCommands``` struct. It provides all the core ```Vulkan``` commands as methods. When ```VkCoreCommands``` is initially created by calling ```VkCoreCommands::new()```, it will already have the *3 global commands* loaded and ready to use. If you attempt to call any of the unloaded commands at this point it will result in *panic*. The next step should be to create a ```VkInstance``` object and call ```VkCoreCommands::load(&mut self, VkInstance instance)``` method passing it as argument. Vulkan is ready to use.

Extensions are loaded similarly by ```VkKhrSurfaceCommands```, ```VkKhrSwapchainCommands```, ```VkKhrDisplayCommands```, ```VkKhrDisplaySwapchainCommands```, ```VkKhrWin32SurfaceCommands```

*One thing this library does not support is loading device optimized command pointers using ```vkGetDeviceProcAddr```. The reason for this omission is that loading functions in this way introduces a lot of incidental complexity and makes library awkward to use.*

## Platform types

Platform types are redefined to avoid operating system specific dependencies, use ```std::mem::transmute``` to cast between them. The current platform types are:

* ```dvk::khr_win32_surface::platform::HINSTANCE```
* ```dvk::khr_win32_surface::platform::HWND```

## Unions
Since Rust has no analog to *C unions* they are simulated using combination of *tagged union types* and a ```From``` *trait*. Whenever Vulkan demands a union with a name ```VkSomeTypeName```, construct a value of type ```VkSomeTypeNameUnion``` and call ```into(self)``` method on it to get ```VkSomeTypeName```. For example:

	let foo: VkClearColorValue = VkClearColorValueUnion::Float32([1,2,3]).into();

## Handles
All handles are type-safe, which unfortunately makes it awkward to produce "NULL" handles. For that reason all handle types implement ```null``` function to construct empty handles, as well as corresponding method ```is_null``` to check if a handle is empty.

## Usage
Here's a short example to illustrate basic use

	#[macro_use]
	extern crate dvk;
	
	use dvk::core::*;
	use dvk::khr_surface::*;
	use dvk::khr_win32_surface::*;
	
	...
	// This will load vulkan shared library and 3 global commands
	let mut core = VkCoreCommands::new().unwrap(); 
	
	// The null method is used to get type-safe "NULL" handles
	let mut instance = VkInstance::null();
	
	// vkCreateInstance is one of the 3 global commands
	// that can be loaded without an instance object
	core.vkCreateInstance(&instance_create_info, null(), &mut context.instance);
	
	// Calling unloaded command will cause a panic
	core.vkEnumeratePhysicalDevices(...); // ERROR!
	
	// After you've acquired an instance object the remaining commands can be loaded
	core.load(instance).unwrap(); 
	
	// The rest of commands are loaded and ready to use now
	core.vkEnumeratePhysicalDevices(...); 
	core.vkCreateDevice(...); 
	core.vkQueueSubmit(...);
	
	// Using intermediate VkClearValueUnion Rust-style enum to 
	// construct VkClearValue corresponding to C-style union
	let clear_depth_stencil_value = VkClearDepthStencilValue{depth:0.0f32, stencil: 0u32};
	let clear_value: VkClearValue = VkClearValueUnion::DepthStencil(clear_depth_stencil_value).into();

# Sample code
A more complete example is available in ```examples/triangle.rs```. To compile( or run) it do:
```
> cargo build(or run) --examples triangle
```