Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release ash 0.38.0 and ash-window 0.13.0 #897

Merged
merged 1 commit into from
Apr 1, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 61 additions & 7 deletions Changelog.md
Original file line number Diff line number Diff line change
@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased] - ReleaseDate

## [0.38.0] - 2024-04-01

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)
@@ -44,10 +95,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- 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, for the following extensions: (#734)
- 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`
@@ -58,10 +115,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `VK_KHR_fragment_shading_rate`
- `VK_EXT_full_screen_exclusive`
- `VK_NV_optical_flow`
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`
- `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)
@@ -81,7 +134,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- 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`, flattened `ash::vk::*` extension modules into `ash::vk`, and moved `*Fn` function pointer table structs from `ash::vk` into `ash` or the associated extension module (#894)
- Flattened `ash::extensions` into `ash`, and moved `*Fn` function pointer table structs from `ash::vk` into `ash` or the associated extension module (#894)

### Removed

@@ -470,7 +523,8 @@ flags: vk::CommandPoolCreateFlags::RESET_COMMAND_BUFFER_BIT,
- `ash::util::Align` is a helper struct that
can write to aligned memory.

[Unreleased]: https://github.com/ash-rs/ash/compare/0.37.2...HEAD
[Unreleased]: https://github.com/ash-rs/ash/compare/0.38.0...HEAD
[0.38.0]: https://github.com/ash-rs/ash/releases/tag/0.38.0
[0.37.2]: https://github.com/ash-rs/ash/releases/tag/0.37.2
[0.37.1]: https://github.com/ash-rs/ash/releases/tag/0.37.1
[0.37.0]: https://github.com/ash-rs/ash/releases/tag/0.37.0
21 changes: 11 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -17,6 +17,7 @@ A very lightweight wrapper around Vulkan
- [x] Additional type safety
- [x] Device local function pointer loading
- [x] No validation, everything is **unsafe**
- [x] Lifetime-safety on structs created with the builder pattern
- [x] Generated from `vk.xml`
- [x] Support for Vulkan `1.1`, `1.2`, `1.3`
- [x] `no_std` support
@@ -146,11 +147,11 @@ Custom loaders can be implemented.

### Extension loading

Additionally, every Vulkan extension has to be loaded explicitly. You can find all extensions under [`ash::extensions`](https://github.com/ash-rs/ash/tree/master/ash/src/extensions).
Additionally, every Vulkan extension has to be loaded explicitly. You can find all extensions directly under `ash::*` in a module with their prefix (e.g. `khr` or `ext`).

```rust
use ash::extensions::khr::Swapchain;
let swapchain_loader = Swapchain::new(&instance, &device);
use ash::khr;
let swapchain_loader = khr::swapchain::Device::new(&instance, &device);
let swapchain = swapchain_loader.create_swapchain(&swapchain_create_info).unwrap();
```

@@ -165,13 +166,13 @@ device.fp_v1_0().destroy_device(...);
### Support for extension names

```rust
use ash::extensions::{Swapchain, XlibSurface, Surface, DebugReport};
use ash::{ext, khr};
#[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()
khr::surface::NAME.as_ptr(),
khr::xlib_surface::NAME.as_ptr(),
ext::debug_utils::NAME.as_ptr(),
]
}
```
@@ -236,7 +237,7 @@ Displays a triangle with vertex colors.
cargo run -p ash-examples --bin triangle
```

![screenshot](http://i.imgur.com/PQZcL6w.jpg)
![screenshot](https://i.imgur.com/PQZcL6w.jpg)

### [Texture](https://github.com/ash-rs/ash/blob/master/ash-examples/src/bin/texture.rs)

@@ -246,7 +247,7 @@ Displays a texture on a quad.
cargo run -p ash-examples --bin texture
```

![texture](http://i.imgur.com/trow00H.png)
![texture](https://i.imgur.com/trow00H.png)

## Useful resources

@@ -270,7 +271,7 @@ cargo run -p ash-examples --bin texture
## A thanks to

- [Api with no secrets](https://software.intel.com/en-us/articles/api-without-secrets-introduction-to-vulkan-part-1)
- [Vulkan tutorial](http://jhenriques.net/development.html)
- [Vulkan tutorial](https://jhenriques.net/development.html)
- [Vulkan examples](https://github.com/SaschaWillems/Vulkan)
- [Vulkan tutorial](https://vulkan-tutorial.com/)
- [Vulkano](https://github.com/vulkano-rs/vulkano)
6 changes: 3 additions & 3 deletions ash-window/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "ash-window"
version = "0.12.0"
version = "0.13.0"
authors = [
"msiglreith <m.siglreith@gmail.com>",
"Marijn Suijten <marijn@traverseresearch.nl>",
@@ -19,15 +19,15 @@ edition = "2021"
rust-version = "1.69.0"

[dependencies]
ash = { path = "../ash", version = "0.37", default-features = false, features = ["std"] }
ash = { path = "../ash", version = "0.38", default-features = false, features = ["std"] }
raw-window-handle = "0.6"

[target.'cfg(any(target_os = "macos", target_os = "ios"))'.dependencies]
raw-window-metal = "0.4"

[dev-dependencies]
winit = { version = "0.29", features = ["rwh_06"] }
ash = { path = "../ash", version = "0.37", default-features = false, features = ["linked"] }
ash = { path = "../ash", version = "0.38", default-features = false, features = ["linked"] }

[[example]]
name = "winit"
6 changes: 4 additions & 2 deletions ash-window/Changelog.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# Changelog

## [Unreleased] - ReleaseDate
## [0.13.0] - 2024-03-31

- Bumped MSRV from 1.59 to 1.69 for `winit 0.28` and `raw-window-handle 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) (#TODO)

## [0.12.0] - 2022-09-23

@@ -86,7 +87,8 @@
## Version 0.1.0
Initial release for `raw-window-handle = "0.3"` with Windows, Linux, Android, MacOS/iOS support.

[Unreleased]: https://github.com/ash-rs/ash/compare/ash-window-0.12.0...HEAD
[Unreleased]: https://github.com/ash-rs/ash/compare/ash-window-0.13.0...HEAD
[0.12.0]: https://github.com/ash-rs/ash/releases/tag/ash-window-0.13.0
[0.12.0]: https://github.com/ash-rs/ash/releases/tag/ash-window-0.12.0
[0.11.0]: https://github.com/ash-rs/ash/releases/tag/ash-window-0.11.0
[0.10.0]: https://github.com/ash-rs/ash/releases/tag/ash-window-0.10.0
2 changes: 1 addition & 1 deletion ash/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "ash"
version = "0.37.0+1.3.281"
version = "0.38.0+1.3.281"
authors = [
"Maik Klein <maikklein@googlemail.com>",
"Benjamin Saunders <ben.e.saunders@gmail.com>",
7 changes: 6 additions & 1 deletion ash/src/entry.rs
Original file line number Diff line number Diff line change
@@ -64,7 +64,12 @@ impl Entry {

#[cfg(all(
unix,
not(any(target_os = "macos", target_os = "ios", target_os = "android", target_os = "fuchsia"))
not(any(
target_os = "macos",
target_os = "ios",
target_os = "android",
target_os = "fuchsia"
))
))]
const LIB_PATH: &str = "libvulkan.so.1";