Migrate core gpu-allocator crate and basic examples to windows-rs

As has long been planned and discussed we'd like to get rid of the
ancient and barely maintained `winapi` crate, in favour of something
more modern: `windows-rs` is actively developed and maintained by
Microsoft themselves, and generated out of header metadata rather than
written by hand.  Besides, it provides a more sophisticated and safer
API for dealing with objects (abstracting away return types behind
`Result`, hiding COM lifetime management, etc).

The choice for the "heavier" `windows` crate over `windows-sys` is
fairly obvious: DirectX APIs are built on the COM object model which is
completely unsupported in `windows-sys` making us unable to perform any
method calls.  Besides, the `windows-sys` crate does very little to make
the API more convenient nor safer to use, effectively taking us a step
back from `winapi` instead of a step forward.

Author: MarijnS95

Cargo.toml

@@ -28,9 +28,21 @@ ash = { version = "0.36", optional = true, default-features = false, features =
 imgui = { version = "0.8", optional = true }
 
 [target.'cfg(windows)'.dependencies]
-# Only needed for d3d12.
+# Only needed for public-winapi interop helpers
 winapi = { version = "0.3.9", features = ["d3d12", "winerror", "impl-default", "impl-debug"], optional = true }
 
+[target.'cfg(windows)'.dependencies.windows]
+version = "0.34"
+features = [
+    "Win32_Foundation",
+    "Win32_Graphics",
+    "Win32_Graphics_Direct3D",
+    "Win32_Graphics_Direct3D12",
+    "Win32_Graphics_Dxgi",
+    "Win32_Graphics_Dxgi_Common",
+]
+optional = true
+
 [dev-dependencies]
 # Enable the "loaded" feature to be able to access the Vulkan entrypoint.
 ash = { version = "0.36", default-features = false, features = ["debug", "loaded"] }
@@ -77,7 +89,8 @@ required-features = ["d3d12", "public-winapi", "visualizer"]
 [features]
 visualizer = ["imgui"]
 vulkan = ["ash"]
-d3d12 = ["winapi"]
+d3d12 = ["windows"]
+# Expose helper functionality for winapi types to interface with gpu-allocator, which is primarily windows-rs driven
 public-winapi = ["winapi"]
 
-default = ["d3d12", "vulkan", "public-winapi"]
+default = ["d3d12", "vulkan"]

README.md

@@ -17,12 +17,19 @@ gpu-allocator = "0.17.0"
 
 This crate provides a fully written in Rust memory allocator for Vulkan and DirectX 12.
 
+### [Windows-rs] and [winapi]
+
+`gpu-allocator` recently migrated from [winapi] to [windows-rs] but still provides convenient helpers to convert to and from [winapi] types, enabled when compiling with the `public-winapi` crate feature.
+
+[Windows-rs]: https://github.com/microsoft/windows-rs
+[winapi]: https://github.com/retep998/winapi-rs
+
 ### Setting up the Vulkan memory allocator
 
 ```rust
 use gpu_allocator::vulkan::*;
 
-let mut allocator = Allocator::new(&AllocatorCreateDesc {
+let mut allocator = Allocator::new(AllocatorCreateDesc {
     instance,
     device,
     physical_device,
@@ -67,7 +74,7 @@ unsafe { device.destroy_buffer(buffer, None) };
 ```rust
 use gpu_allocator::d3d12::*;
 
-let mut allocator = Allocator::new(&AllocatorCreateDesc {
+let mut allocator = Allocator::new(AllocatorCreateDesc {
     device,
     debug_settings: Default::default(),
 });
@@ -80,20 +87,20 @@ use gpu_allocator::d3d12::*;
 use gpu_allocator::MemoryLocation;
 
 
-let buffer_desc = d3d12::D3D12_RESOURCE_DESC {
-    Dimension: d3d12::D3D12_RESOURCE_DIMENSION_BUFFER,
+let buffer_desc = Direct3D12::D3D12_RESOURCE_DESC {
+    Dimension: Direct3D12::D3D12_RESOURCE_DIMENSION_BUFFER,
     Alignment: 0,
     Width: 512,
     Height: 1,
     DepthOrArraySize: 1,
     MipLevels: 1,
-    Format: dxgiformat::DXGI_FORMAT_UNKNOWN,
-    SampleDesc: dxgitype::DXGI_SAMPLE_DESC {
+    Format: Dxgi::Common::DXGI_FORMAT_UNKNOWN,
+    SampleDesc: Dxgi::Common::DXGI_SAMPLE_DESC {
         Count: 1,
         Quality: 0,
     },
-    Layout: d3d12::D3D12_TEXTURE_LAYOUT_ROW_MAJOR,
-    Flags: d3d12::D3D12_RESOURCE_FLAG_NONE,
+    Layout: Direct3D12::D3D12_TEXTURE_LAYOUT_ROW_MAJOR,
+    Flags: Direct3D12::D3D12_RESOURCE_FLAG_NONE,
 };
 let allocation_desc = AllocationCreateDesc::from_d3d12_resource_desc(
     allocator.device(),
@@ -102,24 +109,20 @@ let allocation_desc = AllocationCreateDesc::from_d3d12_resource_desc(
     MemoryLocation::GpuOnly,
 );
 let allocation = allocator.allocate(&allocation_desc).unwrap();
-let mut resource: *mut d3d12::ID3D12Resource = std::ptr::null_mut();
+let mut resource: Option<Direct3D12::ID3D12Resource> = None;
 let hr = unsafe {
-    device.as_ref().unwrap().CreatePlacedResource(
-        allocation.heap().as_winapi_mut(),
+    device.CreatePlacedResource(
+        allocation.heap(),
         allocation.offset(),
         &buffer_desc,
-        d3d12::D3D12_RESOURCE_STATE_COMMON,
+        Direct3D12::D3D12_RESOURCE_STATE_COMMON,
         std::ptr::null(),
-        &d3d12::IID_ID3D12Resource,
-        &mut resource as *mut _ as *mut _,
+        &mut resource,
     )
-};
-if hr != winerror::S_OK {
-    panic!("Failed to create placed resource.");
-}
+}?;
 
 // Cleanup
-unsafe { resource.as_ref().unwrap().Release() };
+drop(resource);
 allocator.free(allocation).unwrap();
 ```
 

examples/d3d12-buffer-winrs.rs

@@ -1,5 +1,6 @@
+//! Example showcasing [`gpu-allocator`] with types and functions from the [`windows`] crate.
 use gpu_allocator::d3d12::{
-    AllocationCreateDesc, Allocator, AllocatorCreateDesc, Dx12DevicePtr, ResourceCategory,
+    AllocationCreateDesc, Allocator, AllocatorCreateDesc, ResourceCategory,
 };
 use gpu_allocator::MemoryLocation;
 use log::error;
@@ -9,7 +10,7 @@ use windows::Win32::{
     Graphics::{
         Direct3D::{D3D_FEATURE_LEVEL_11_0, D3D_FEATURE_LEVEL_11_1, D3D_FEATURE_LEVEL_12_0},
         Direct3D12::{
-            D3D12CreateDevice, ID3D12Device, ID3D12Heap, ID3D12Resource,
+            D3D12CreateDevice, ID3D12Device, ID3D12Resource,
             D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT, D3D12_RESOURCE_DESC,
             D3D12_RESOURCE_DIMENSION_BUFFER, D3D12_RESOURCE_FLAG_NONE, D3D12_RESOURCE_STATE_COMMON,
             D3D12_TEXTURE_LAYOUT_ROW_MAJOR,
@@ -82,11 +83,9 @@ fn main() -> Result<()> {
 
     let device = create_d3d12_device(&dxgi_factory).expect("Failed to create D3D12 device.");
 
-    let device_ptr: Dx12DevicePtr = unsafe { std::mem::transmute_copy(&device) };
-
     // Setting up the allocator
-    let mut allocator = Allocator::new(&AllocatorCreateDesc {
-        device: device_ptr,
+    let mut allocator = Allocator::new(AllocatorCreateDesc {
+        device: device.clone(),
         debug_settings: Default::default(),
     })
     .unwrap();
@@ -111,18 +110,16 @@ fn main() -> Result<()> {
 
         let allocation_desc = AllocationCreateDesc::from_d3d12_resource_desc(
             allocator.device(),
-            // Raw structs are binary-compatible
-            unsafe { std::mem::transmute(&test_buffer_desc) },
+            &test_buffer_desc,
             "Test allocation (Gpu only)",
             MemoryLocation::GpuOnly,
         );
         let allocation = allocator.allocate(&allocation_desc).unwrap();
 
         let mut resource: Option<ID3D12Resource> = None;
-        let heap: &ID3D12Heap = unsafe { std::mem::transmute(&allocation.heap()) };
         unsafe {
             device.CreatePlacedResource(
-                heap,
+                allocation.heap(),
                 allocation.offset(),
                 &test_buffer_desc,
                 D3D12_RESOURCE_STATE_COMMON,
@@ -168,10 +165,9 @@ fn main() -> Result<()> {
             .unwrap();
 
         let mut resource: Option<ID3D12Resource> = None;
-        let heap: &ID3D12Heap = unsafe { std::mem::transmute(&allocation.heap()) };
         unsafe {
             device.CreatePlacedResource(
-                heap,
+                allocation.heap(),
                 allocation.offset(),
                 &test_buffer_desc,
                 D3D12_RESOURCE_STATE_COMMON,
@@ -217,10 +213,9 @@ fn main() -> Result<()> {
             .unwrap();
 
         let mut resource: Option<ID3D12Resource> = None;
-        let heap: &ID3D12Heap = unsafe { std::mem::transmute(&allocation.heap()) };
         unsafe {
             device.CreatePlacedResource(
-                heap,
+                allocation.heap(),
                 allocation.offset(),
                 &test_buffer_desc,
                 D3D12_RESOURCE_STATE_COMMON,
@@ -235,7 +230,5 @@ fn main() -> Result<()> {
         println!("Allocation and deallocation of CpuToGpu memory was successful.");
     }
 
-    drop(allocator); // Explicitly drop before destruction of device.
-
     Ok(())
 }

examples/d3d12-buffer.rs

@@ -1,3 +1,4 @@
+//! Example showcasing [`winapi`] interop with [`gpu-allocator`] which is driven by the [`windows`] crate.
 use winapi::shared::{dxgiformat, winerror};
 use winapi::um::{d3d12, d3dcommon};
 use winapi::Interface;
@@ -9,8 +10,7 @@ mod all_dxgi {
 use log::*;
 
 use gpu_allocator::d3d12::{
-    AbstractWinapiPtr, AllocationCreateDesc, Allocator, AllocatorCreateDesc, Dx12DevicePtr,
-    ResourceCategory,
+    AllocationCreateDesc, Allocator, AllocatorCreateDesc, ResourceCategory, ToWinapi, ToWindows,
 };
 use gpu_allocator::MemoryLocation;
 
@@ -68,7 +68,7 @@ fn create_d3d12_device(
                     };
                     match hr {
                         winapi::shared::winerror::S_OK => {
-                            info!("Using D3D12 feature level: {}.", feature_level_name);
+                            println!("Using D3D12 feature level: {}.", feature_level_name);
                             Some(device)
                         }
                         winapi::shared::winerror::E_NOINTERFACE => {
@@ -114,12 +114,14 @@ fn main() {
     let device = create_d3d12_device(dxgi_factory).expect("Failed to create D3D12 device.");
 
     // Setting up the allocator
-    let mut allocator = Allocator::new(&AllocatorCreateDesc {
-        device: Dx12DevicePtr(device.cast()),
+    let mut allocator = Allocator::new(AllocatorCreateDesc {
+        device: device.as_windows().clone(),
         debug_settings: Default::default(),
     })
     .unwrap();
 
+    let device = unsafe { device.as_ref() }.unwrap();
+
     // Test allocating Gpu Only memory
     {
         let test_buffer_desc = d3d12::D3D12_RESOURCE_DESC {
@@ -138,8 +140,8 @@ fn main() {
             Flags: d3d12::D3D12_RESOURCE_FLAG_NONE,
         };
 
-        let allocation_desc = AllocationCreateDesc::from_d3d12_resource_desc(
-            allocator.device(),
+        let allocation_desc = AllocationCreateDesc::from_winapi_d3d12_resource_desc(
+            device,
             &test_buffer_desc,
             "Test allocation (Gpu Only)",
             MemoryLocation::GpuOnly,
@@ -148,8 +150,8 @@ fn main() {
 
         let mut resource: *mut d3d12::ID3D12Resource = std::ptr::null_mut();
         let hr = unsafe {
-            device.as_ref().unwrap().CreatePlacedResource(
-                allocation.heap().as_winapi_mut(),
+            device.CreatePlacedResource(
+                allocation.heap().as_winapi() as *mut _,
                 allocation.offset(),
                 &test_buffer_desc,
                 d3d12::D3D12_RESOURCE_STATE_COMMON,
@@ -165,7 +167,7 @@ fn main() {
         unsafe { resource.as_ref().unwrap().Release() };
 
         allocator.free(allocation).unwrap();
-        info!("Allocation and deallocation of GpuOnly memory was successful.");
+        println!("Allocation and deallocation of GpuOnly memory was successful.");
     }
 
     // Test allocating Cpu to Gpu memory
@@ -186,12 +188,7 @@ fn main() {
             Flags: d3d12::D3D12_RESOURCE_FLAG_NONE,
         };
 
-        let alloc_info = unsafe {
-            device
-                .as_ref()
-                .unwrap()
-                .GetResourceAllocationInfo(0, 1, &test_buffer_desc)
-        };
+        let alloc_info = unsafe { device.GetResourceAllocationInfo(0, 1, &test_buffer_desc) };
 
         let allocation = allocator
             .allocate(&AllocationCreateDesc {
@@ -205,8 +202,8 @@ fn main() {
 
         let mut resource: *mut d3d12::ID3D12Resource = std::ptr::null_mut();
         let hr = unsafe {
-            device.as_ref().unwrap().CreatePlacedResource(
-                allocation.heap().as_winapi_mut(),
+            device.CreatePlacedResource(
+                allocation.heap().as_winapi() as *mut _,
                 allocation.offset(),
                 &test_buffer_desc,
                 d3d12::D3D12_RESOURCE_STATE_COMMON,
@@ -222,7 +219,7 @@ fn main() {
         unsafe { resource.as_ref().unwrap().Release() };
 
         allocator.free(allocation).unwrap();
-        info!("Allocation and deallocation of CpuToGpu memory was successful.");
+        println!("Allocation and deallocation of CpuToGpu memory was successful.");
     }
 
     // Test allocating Gpu to Cpu memory
@@ -243,12 +240,7 @@ fn main() {
             Flags: d3d12::D3D12_RESOURCE_FLAG_NONE,
         };
 
-        let alloc_info = unsafe {
-            device
-                .as_ref()
-                .unwrap()
-                .GetResourceAllocationInfo(0, 1, &test_buffer_desc)
-        };
+        let alloc_info = unsafe { device.GetResourceAllocationInfo(0, 1, &test_buffer_desc) };
 
         let allocation = allocator
             .allocate(&AllocationCreateDesc {
@@ -262,8 +254,8 @@ fn main() {
 
         let mut resource: *mut d3d12::ID3D12Resource = std::ptr::null_mut();
         let hr = unsafe {
-            device.as_ref().unwrap().CreatePlacedResource(
-                allocation.heap().as_winapi_mut(),
+            device.CreatePlacedResource(
+                allocation.heap().as_winapi() as *mut _,
                 allocation.offset(),
                 &test_buffer_desc,
                 d3d12::D3D12_RESOURCE_STATE_COMMON,
@@ -279,10 +271,10 @@ fn main() {
         unsafe { resource.as_ref().unwrap().Release() };
 
         allocator.free(allocation).unwrap();
-        info!("Allocation and deallocation of CpuToGpu memory was successful.");
+        println!("Allocation and deallocation of CpuToGpu memory was successful.");
     }
 
     drop(allocator); // Explicitly drop before destruction of device.
-    unsafe { device.as_ref().unwrap().Release() };
+    unsafe { device.Release() };
     unsafe { dxgi_factory.as_ref().unwrap().Release() };
 }