From 568fe0bb11c16c05f289b66103f0dc9eed6b6614 Mon Sep 17 00:00:00 2001
From: maik klein <maikklein@googlemail.com>
Date: Sun, 1 Jan 2017 08:31:13 +0100
Subject: [PATCH] Update the readme for the new loader

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 50 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 27b7102..c212ea9 100644
--- a/README.md
+++ b/README.md
@@ -17,10 +17,8 @@ I don't expect any big changes anymore. The library will still remain < 1.0 unti
 ## Why Ash?
 - [x] Lightweight Vulkan wrapper
 - [x] Low overhead
-- [x] Added type safety
-- [x] More convenient to use than raw Vulkan
-- [x] Includes a loader
-- [x] Extensions have their own loader
+- [x] Additional type safety
+- [x] Trait based, version specific loader
 
 ## What does it do?
 
@@ -104,12 +102,42 @@ Additionally pointers like `Instance`, `Device`, `Queue` etc are hidden behind a
 
 ### Function pointer loading
 Ash also takes care of loading the function pointers. Function pointers are split into 3 categories. Entry, Instance and Device. The reason for not loading it into a global is that in Vulkan you can have multiple devices and each device must load its own function pointers.
+
+Ash also manages multiple versions of Vulkan without any breakage. You will never run into any runtime error because you tried to access a function pointer that failed to load. Function pointers either load successfully or fail and return an error.
+
 ```Rust
-// Looks for the vulkan lib in your path, alternatively you can supply the path explicitly.
-let entry = Entry::load_vulkan().unwrap();
-let instance: Instance = entry.create_instance(&create_info).expect("Instance creation error");
-let device: Device = instance.create_device(pdevice, &device_create_info)
-    .unwrap();
+use ash::{Device, Instance};
+// Specifies the version that you want to load
+use ash::version::V1_0;
+// Those traits implement the version specific functions
+use ash::{InstanceV1_0, DeviceV1_0};
+let entry = Entry::<V1_0>::load_vulkan().unwrap();
+let instance = entry.create_instance(...).expect("Instance creation error.");
+let device = instance.create_device(...).expect("Device creation error.");
+```
+
+```Rust
+// Define your types
+type YourDevice = Device<V1_0>;
+type YourInstance = Instance<V1_0>;
+```
+
+You can upgrade to future version without any breakage. 
+```Rust
+// For example, switching from V1_0 to V1_3 will not cause any breakage.
+type YourDevice = Device<V1_3>;
+type YourInstance = Instance<V1_3>;
+```
+
+A newer version can always be converted to an older version.
+```Rust
+let newer_device: Device<V1_5> = ...;
+let older_device: Device<V1_0> = newer_device.into();
+```
+
+Or specify the *minimum* version that you require with a trait.
+```Rust
+fn do_something_with_a_device<Device: DeviceV1_0>(device: &Device){}
 ```
 
 ### Extension loading
@@ -120,6 +148,19 @@ let swapchain_loader = Swapchain::new(&instance, &device).expect("Unable to load
 let swapchain = swapchain_loader.create_swapchain_khr(&swapchain_create_info).unwrap();
 ```
 
+### Support for extension names
+```Rust
+use ash::extensions::{Swapchain, XlibSurface, Surface, DebugReport};
+#[cfg(all(unix, not(target_os = "android")))]
+fn extension_names() -> Vec<*const i8> {
+    vec![
+        Surface::name().as_ptr(),
+        XlibSurface::name().as_ptr(),
+        DebugReport::name().as_ptr()
+    ]
+}
+```
+
 ### Implicit handles
 You don't have to pass an Instance or Device handle anymore, this is done implicitly for you. This makes sure that you will always use the most optimal implementation for your `Device`.
 ```Rust
@@ -138,18 +179,6 @@ pub fn create_command_pool(&self,
 let pool = device.create_command_pool(&pool_create_info).unwrap();
 ```
 
-### Support for extension names
-```Rust
-use ash::extensions::{Swapchain, XlibSurface, Surface, DebugReport};
-#[cfg(all(unix, not(target_os = "android")))]
-fn extension_names() -> Vec<*const i8> {
-    vec![
-        Surface::name().as_ptr(),
-        XlibSurface::name().as_ptr(),
-        DebugReport::name().as_ptr()
-    ]
-}
-```
 ## Example
 You can find the examples [here](https://github.com/MaikKlein/ash/tree/master/examples).
 All examples currently require: the LunarG Validation layers and a Vulkan library that is visible in your `PATH`. An easy way to get start is to use the [LunarG Vulkan SDK](https://lunarg.com/vulkan-sdk/)