With over two years of collecting breaking changes (since the `0.37.0…

…` release in March 2022), April 2024 marks the next breaking release of `ash`. This release introduces an overhaul of all Vulkan structures, restructures modules around extensions, and separates extension wrappers between `Instance` and `Device` functions. The crate contains all bindings defined by the latest `1.3.281` Vulkan specification, and many old and new extensions have received a hand-written extension wrapper. For a full overview of all individual changes, see the list at the end of this post.

* Replaced builders with lifetimes/setters directly on Vulkan structs

All `Builder` structs have been removed, and their builder functions and lifetime generic have moved to the underlying Vulkan struct.  This means all types will carry the lifetime information of contained references at all times, when created using the builder pattern.

Where one used to call:

```rust
let queue_info = [vk::DeviceQueueCreateInfo::build()
    .queue_family_index(queue_family_index)
    .queue_priorities(&priorities)
    .build()];
```

Which drops lifetime information about the `&priorities` slice borrow, one now writes:

```rust
let queue_info = [vk::DeviceQueueCreateInfo::default()
    .queue_family_index(queue_family_index)
    .queue_priorities(&priorities)];
```

And `queue_info` relies on the borrow checker to ensure it cannot outlive `&priorities`.

* Separating extension loaders and wrappers between `instance` and `device` functions

Just like the separation between `InstanceFnV1_x` and `Device_FnV1_x` for Vulkan core functions, all extensions now have a separate generated `InstanceFn` and `DeviceFn` function pointer table (when containing one or more functions), separating out the two.

High-level extension wrappers are updated to match via a separate `Instance` and `Device` struct inside a module carrying the extension name (see also below), instead of residing in a single struct.  These modules are generated for all extensions including those without functions (for which no `Instance` or `Device` struct is generated), complete with a reexport of the extension name and version.

* Restructuring of modules around extensions, function-pointer tables and high-level wrappers

Function pointer tables for both core and extensions have moved out of the "pure" `sys`-like `ash::vk::` module, into the `ash::` root for core `*FnV1_x` tables and into the extension module `ash::<prefix>::<extension name>::{InstanceFn, DeviceFn}` for extensions.  High-level wrappers for these structs (originally from the `ash::extensions` module), together with the `Instance` and `Device` structure split detailed above, have also moved into this module.

For example, `ash::vk::KhrSwapchainFn` is now available as `ash::khr::swapchain::{InstanceFn, DeviceFn}`, and the high-level `ash::extensions::KhrSwapchain` wrapper is available at `ash::khr::swapchain::{Instance, Device}`.  The extension name and version are found under `ash::khr::swapchain::{NAME, SPEC_VERSION}`.

* Misc helpers

Various miscellaneous helpers have been introduced on low-level Vulkan structs.

For statically-sized arrays with a field bounding their length (e.g. `ash::vk::PhysicalDeviceMemoryProperties::memory_types` with the `memory_types_count` field) a new `_as_slice()` getter is available to retrieve the initialized portion of the slice.

For null-terminated strings stored in statically-sized arrays, both `_as_c_str()` getters and more convenient setter is introduced based on the `CStr` type, providing `Result`-based access to these fields.

* `no_std` support

By disabling the default `std` feature, this crate compiles in a [`no_std` environment](https://docs.rust-embedded.org/book/intro/no-std.html).

***

Added

- Added `std` feature. Disabling this feature makes ash `no_std` (#664)
- Added `Handle::is_null()` to allow checking if a handle is a `NULL` value (#694)
- Allow building `Entry`/`Instance`/`Device` from handle+fns (see their `from_parts_1_x()` associated functions) (#748)
- Update Vulkan-Headers to 1.3.281 (#760, #763, #783, #816, #840)
- Added `VK_NV_memory_decompression` device extension (#761)
- Added `VK_GOOGLE_display_timing` device extension (#765)
- Added `VK_ANDROID_external_memory_android_hardware_buffer` device extension (#769)
- Added `VK_AMD_buffer_marker` device extension (#772)
- Added `VK_AMD_shader_info` device extension (#773)
- Added `VK_AMDX_shader_enqueue` device extension (#776)
- Added `VK_EXT_host_image_copy` device extension (#779)
- Added `VK_KHR_maintenance5` device extension (#780)
- Added `VK_NV_device_generated_commands_compute` device extension (#781)
- Added `VK_KHR_cooperative_matrix` instance extension (#782)
- Added `VK_EXT_vertex_input_dynamic_state` device extension (#784)
- Added `VK_KHR_sampler_ycbcr_conversion` device extension (#785)
- Added `VK_EXT_swapchain_maintenance1` device extension (#786)
- Added `VK_NV_low_latency2` device extension (#802)
- Added `VK_EXT_hdr_metadata` device extension (#804)
- Added `VK_NV_cuda_kernel_launch` device extension (#805)
- Added `descriptor_count()` setter on `ash::vk::WriteDescriptorSet` (#809)
- Added `*_as_c_str()` getters for `c_char` pointers and `c_char` arrays (#831)
- Added `#[must_use]` to Vulkan structs to make it more clear that they are moved by the builder pattern (#845)
- Added `load_with()` function on `Device` and `Instance` for providing custom `get_xxx_proc_addr()` implementations (#846)
- Added `Send`/`Sync` to all Vulkan structs (#869)
- Added `VK_KHR_dynamic_rendering_local_read` device extension (#888)
- Added `VK_KHR_line_rasterization` device extension (#889)
- Added `VK_KHR_calibrated_timestamps` device extension (#890)
- Added `VK_KHR_maintenance6` device extension (#891)
- Added `VK_NV_copy_memory_indirect` device extension (#892)

Changed

- Replaced builders with lifetimes/setters directly on Vulkan structs (#602)
- Inlined struct setters (#602)
- On Fuchsia `libvulkan.so` is now loaded without inexistent `.1` major-version suffix (#626)
- Bumped MSRV from 1.59 to 1.69 (#709, #746)
- Replaced `const fn name()` with associated `NAME` constants (#715)
- Generic builders now automatically set `objecttype` to `<T as Handle>::ObjectType` (#724)
- Separated low-level `*Fn` structs and high-level extension wrappers between instance and device functions, and moved high-level extension wrappers from `ash::extensions::*` to `ash::<prefix>::<extension name>::{Instance, Device}` (#734)
  This not only allows loading `device`-optimized function pointers, it also prevents accidentally loading `instance` functions via `get_device_proc_addr()` which would always return `NULL`, making these `instance` functions always panic on the following high-level extension wrappers:
  - `VK_KHR_swapchain`
  - `VK_KHR_device_group`
  - `VK_EXT_full_screen_exclusive`
  The following extensions containing `instance`-level functions prevented this panic by loading all functions in the `*Fn` loader struct via `get_instance_proc_addr()`, resulting in extra dispatch code inserted by the loader for all `device`-level functions:
  - `VK_KHR_swapchain`
  - `VK_KHR_video_queue`
  - `VK_KHR_device_group`
  - `VK_KHR_performance_query`
  - `VK_EXT_debug_utils`
  - `VK_EXT_sample_locations`
  - `VK_EXT_calibrated_timestamps`
  - `VK_KHR_fragment_shading_rate`
  - `VK_EXT_full_screen_exclusive`
  - `VK_NV_optical_flow`
- `get_calibrated_timestamps()` now returns a single value for `max_deviation` (#738)
- Bumped `libloading` from `0.7` to `0.8` (#739)
- extensions/khr: Take the remaining `p_next`-containing structs as `&mut` to allow chains (#744)
  - `AccelerationStructure::get_acceleration_structure_build_sizes()`
  - `ExternalMemoryFd::get_memory_fd_properties()`
  - `ExternalMemoryWin32::get_memory_win32_handle_properties()`
  - `GetSurfaceCapabilities2::get_physical_device_surface_capabilities2()`
- Define `Display` as `c_void` instead of `*mut c_void` to match Xlib (#751)
- `VK_KHR_device_group_creation`: Take borrow of `Entry` in `fn new()` (#753)
- `VK_KHR_device_group_creation`: Rename `vk::Instance`-returning function from `device()` to `instance()` (#759)
- Windows `HANDLE` types (`HWND`, `HINSTANCE`, `HMONITOR`) are now defined as `isize` instead of `*const c_void` (#797)
- extensions: Make all `vk::Pipeline` and `vk::ShaderEXT` creation functions return their impartial result on error (#828)
  - `VK_AMDX_shader_enqueue`
  - `VK_EXT_shader_object`
  - `VK_KHR_ray_tracing_pipeline`
  - `VK_NV_ray_tracing`
- extensions/ext/ray_tracing_pipeline: Pass indirect SBT regions as single item reference (#829)
- Replaced `c_char` array setters with `CStr` setters (#831)
- `push_next()` functions now allow unsized `p_next` argument (#855)
- Flattened `ash::extensions` into `ash`, and moved `*Fn` function pointer table structs from `ash::vk` into `ash` or the associated extension module (#894)

Removed

- Removed all code generated for `"disabled"` extensions, typically with a number rather than a descriptive name (#448)
- Removed experimental AMD extensions (#607)
- Removed `query_count` parameter from `get_query_pool_results()` in favour of `data.len()` (#644)
- Removed misnamed, deprecated `debug_utils_set_object_name()` and `debug_utils_set_object_tag()` entirely, use `set_debug_utils_object_name()` and `set_debug_utils_object_tag()` instead (#661)
- Removed `get_properties` helper from extension wrappers (and `ext::PhysicalDeviceDrm`). Directly call `get_physical_device_properties2()` with a possible chain of multiple structs instead (#728)
- Removed `fn load()` from empty features and extensions (#752)
  - Removed empty `entry_fn_1_2`/`entry_fn_1_3` and getters from `Entry`
  - Removed empty `instance_fn_1_2:` and getters from `Instance`

- Bumped MSRV from 1.59 to 1.69 for `winit 0.28` and `raw-window-hand…

…le 0.5.1`, and `CStr::from_bytes_until_nul`. (#709, #716, #746)

- Bumped `raw-window-handle` to `0.6.0` (#799)
- Bumped `ash` version to [`0.38`](https://github.com/ash-rs/ash/releases/tag/0.38.0) (#897)

Changed

- `VK_KHR_device_group_creation`: Replaced `device()` with `instance()` (via deprecation) because it is returning `vk::Instance` (#744)

Added

- Added `VK_EXT_pipeline_properties` device extension (#622)
- Update Vulkan-Headers to 1.3.251 (#697, #723, #741)
- Added `VK_KHR_performance_query` device extension (#726)
- Added `VK_EXT_shader_object` device extension (#732)
- Added missing `Device::get_device_queue2()` wrapper (#736)
- Added with `new_with_instance()` on the following extensions to allow loading the listed `Instance` functions: (#744)
  - `VK_KHR_swapchain`: `get_physical_device_present_rectangles()`
  - `VK_KHR_device_group`: `get_physical_device_present_rectangles()`
  - `VK_EXT_full_screen_exclusive`: `get_physical_device_surface_present_modes2()`
- Exposed `FramebufferCreateInfoBuilder::attachment_count()` builder for `vk::FramebufferCreateFlags::IMAGELESS` (#747)

Added

- Update Vulkan-Headers to 1.3.238 (#688)

Fixed

- `VK_KHR_draw_indirect_count`: use `cmd_draw_indirect_count_khr` instead of `cmd_draw_indexed_indirect_count_khr` for non-indexed draw call (#695)

Changed

- Inlined builder setters (partial backport from #602)
- Inlined `Default` impls and trivial `Instance`/`Device`/`Entry` wrapper methods (#606, #632)
- Renamed `debug_utils_set_object_name()` to `set_debug_utils_object_name()` and `debug_utils_set_object_tag()` to `set_debug_utils_object_tag()` for consistency and deprecated old ones (#661)

Added

- Added `VK_EXT_image_drm_format_modifier` device extension (#603)
- Set MSRV (Minimum Supported Rust Version) in `Cargo.toml` for clearer errors (#604)
- Update Vulkan-Headers to 1.3.235 (#605, #608, #619, #655, #667)
- Added `const STRUCTURE_TYPE` to all Vulkan structures for matching with `match_struct!` macro (#614)
- Added `VK_EXT_sample_locations` device extension (#616)
- Added `VK_NV_coverage_reduction_mode` device extension (#617)
- Added `VK_KHR_ray_tracing_maintenance1` device extension (#620)
- Added `VK_EXT_image_compression_control` device extension (#621)
- Added new functions to `VK_KHR_swapchain`, available since Vulkan 1.1 (#629)
- Added `VK_KHR_device_group_creation` instance extension (#630)
- Added `VK_KHR_device_group` device extension (#631)
- Added `VK_EXT_mesh_shader` device extension (#657)
- Added `VK_EXT_acquire_drm_display` instance extension (#668)
- Added `VK_EXT_extended_dynamic_state3` device extension (#671)
- Added `VK_EXT_descriptor_buffer` instance extension (#679)

Fixed

- `khr::RayTracingPipeline`: Set the buffer length in `get_ray_tracing_capture_replay_shader_group_handles` so it no longer always returns an empty `Vec` (#658)

Changed

- Bumped `raw-window-handle` to `0.5.0`, now taking `RawDisplayHandle` and `RawWindowHandle` directly
  instead of requiring dynamic dispatch through the `HasRaw{Display,Window}Handle` traits (#645)

Changed

- Bumped `raw-window-handle` to `0.4.2` (#505)

Changed

- Dropped auto-generated wrapper methods from function pointer structs
  in favor of direct invocation of function pointers (#599)
- Constified extension names (#590)
- `VK_NV_device_diagnostic_checkpoints`: Enable passing `pNext`-initialized structs to `get_queue_checkpoint_data` (#588)

Added

- Update Vulkan-Headers to 1.3.209 (#597, #601)
- Added `VK_EXT_headless_surface` instance extension (#589)

- Bumped `ash` version to [`0.37`](https://github.com/MaikKlein/ash/r…

…eleases/tag/0.37.0) (#600)

- Make `enumerate_required_extensions()` return `&[*const c_char]` instead of `Vec<&CStr>` to match `ash::vk::InstanceCreateInfo` (#590)

Changed

- extensions/khr: Drop `_khr` suffix from `get_memory_fd_properties_khr` in `ExternalMemoryFd` (#580)
- entry: Allow querying `enumerate_instance_extension_properties()` by layer name (#574)

Added

- Add helper wrappers for Vulkan core 1.3 `Instance` and `Device` functions (#568)
- Update Vulkan-Headers to 1.3.206 (#563)