0.38.0

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:

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:

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.

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