The docs clearly state:
#[rustc_deprecated(since = "1.42.0", reason = "use the Display impl or to_string()")]
fn description(&self) -> &str {
"description() is deprecated; use Display"
}
We already have a `Display` implementation containing an identical
`match` block and has further improvements on the way in [1].
[1]: https://github.com/MaikKlein/ash/pull/424
Previously, the `Display` impl for `vk::Result` did not include handling
for extension values. For example, `VK_ERROR_OUT_OF_DATE_KHR` would
display simply as `"-1000001004"`. Now, we fall back to the `Debug` impl
of the `Result` if the value is unknown (i.e. from an extension). This
preserves the current nice messages for non-extension values, and the
numeric output for truly unknown values, but displays the enum variant
name (e.g. `"ERROR_OUT_OF_DATE"`) for extension values.
* Fix clippy::use_self warnings in extension modules
* Deny clippy::use_self in extension modules
Note that clippy::use_self generates some false positives that must be ignored
* generator: Generate enums from vk_parse representation
This change prepares for future additions in vk_parse fields ([1]) by
converting over the enum generation path from vkxml. Most of the
conversion is easy by repurposing the existing `EnumSpec` parsing logic
from extension constants for all enumeration variants, with slight
modifications to not bail when `extends` is not set which is specific to
extension constants.
As an (unintended) added bonus this unification of the `EnumSpec`
codepath allows aliases (for backwards-compatible names) to be generated
as discussed earlier in [2].
[1]: https://github.com/krolli/vk-parse/pull/17
[2]: https://github.com/MaikKlein/ash/pull/384#discussion_r588693967
* generator: Turn "backwards"-mentioning docs into deprecation notices
All constant aliases for misspelled items (missing `_BIT` andsoforth)
contain the text "backwards compatibility" or "Backwards-compatible
alias".
* generator: Drop aliases whose name becomes identical after de-mangling
* generator: Remove aliases from const_debugs
These already have a match against the name they're aliasing, and some
of the aliases are "deprecated" (since they're just typo fixups for
backwards compatibility).
* Check for entry point in EntryCustom::new and return error
* Split off into load_checked
* Remove string from MissingEntryPoint
* Change MissingEntryPoint error message
* extensions/khr: Add ExternalSemaphoreFd safe wrapper
Implement the two small import and export and functions, part of the
VK_KHR_external_semaphore_fd extension.
* device: Pass ImageSubresource by immutable reference
It is only used as pointer by the native function, and should not (need
to) be moved.
* ci: Test docs in addition to `cargo t --all-targets`
Unfortunately docs are not explicitly (build-)tested as part of
`--all-targets` allowing broken code to slip in as shown by #390.
Also remove the `rust` listing type which is the default, leaving only
`no_run` (until the CI has a loadable Vulkan library).
* ash: Fix errors and warnings in (now tested) documentation comments
MemoryFdPropertiesKHR is a struct that, despite being used as output,
hsa to be initialized properly with a valid sType set, otherwise:
Validation Error: [ VUID-VkMemoryFdPropertiesKHR-sType-sType ] Object 0: handle = 0x7f035464d648, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0xdc6b3a0d | vkGetMemoryFdPropertiesKHR: parameter pMemoryFdProperties->sType must be VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR. The Vulkan spec states: sType must be VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR (https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VUID-VkMemoryFdPropertiesKHR-sType-sType)
All type parameters are implicitly bound by `Sized`; matching the `&`
out of `&str` implies that `str` must be bound by `Sized` which is not
true, resulting in:
18 | let entry = ash::Entry::with_library("foo")?;
| ^^^^^ doesn't have a size known at compile-time
|
::: /home/marijn/Code/TraverseResearch/ash/ash/src/entry_libloading.rs:73:39
|
73 | pub unsafe fn with_library(path: &impl AsRef<OsStr>) -> Result<Entry, LoadingError> {
| ----------------- required by this bound in `ash::entry_libloading::<impl EntryCustom<Arc<libloading::Library>>>::with_library`
After all `Library::new` accepts an `impl AsRef<OsStr>` without borrow,
which is what this function is modeled after to pass the same parameter
on directly.
Fixes: c6d5d66 ("entry_libloading: Provide Vulkan library loader from custom path (#319)")
* generator: Only replace "VK_" at the start of enum variant names
Replacing the occurence of "VK" is dangerous as shown by this diff; MVK
shorthands for MoltenVK are accidentally mangled. Using
strip_prefix/suffix is not only more correct and performs more runtime
checks, it is also more performant by returning a slice into the string.
* generator: Correct duplicate suffix stripping
The original `.replace(vendor, "")` operation and `.trim_end_matches`
replace every (trailing) occurence of the vendor, causing
DEBUG_REPORT_CALLBACK_EXT_EXT to end up without `_EXT` at all. This name
is also provided by vk.xml as fallback alias because it is used but
technically incorrect; the current generator can however not generate it
(limitation in vkxml representation).
Constants (enumeration bitflags) containing the word `external` were not
stripped of their common typename, and quick debugging showed the word
`VKTERNAL_...` in `struct_name`. `_EXT` would be the first extension to
match in `VK_EXTERNAL_...` messing up `struct_name` with a global
`.replace`, in turn not removing it from the variant name.
It isn't too uncommon to pass a single builder element into another
builder, and `slice::from_ref` fits perfectly while preserving lifetime
of the builder without calling `.build()`. We have used this
successfully in our codebase to uncover and prevent numerous
use-after-free bugs, and thought it's worth to share on the front page.
* khr/acceleration_structure: Fix fn signature of indirect build cmd
max_primitive_counts is an array of arrays, not an array of references
to single u32's.
* khr/acceleration_structure: Validate array length against geometry_count
This is a safe wrapper that already iterates over all the slice
references (fat pointers) to collect just the pointers for use in the
Vulkan API. It can and should at the same time make sure these slices
are of the specified length to prevent accidental out-of-bounds reads.
CString::new needs to perform an allocation to own the `&'static str`
and append a NULL byte to it. We can instead perform this "allocation"
in the generator and emit a byte-string literal with trailing NULL byte
that can immediately be used by the function loader.
This handle is already held onto when creating the safe wrapper object,
but is inconsistently required again in some but not all functions.
Remove it from every function and use the internal handle instead.
Closes: #377
Fixes: 05747b2 ("Update Vulkan-Headers to 1.2.162 with stable ray-tracing spec (#341)")
This new version marks `Library::new` as unsafe, because loading a
library invokes the libraries' entrypoint which may or may not have
certain preconditions and perform unsafe/undefined operations, just like
any other native function loaded through `libloading`.
`c_void` is not the same as Rust's void type, `()`, making function
pointers like `PFN_vkFreeFunction` pretty much impossible to implement
without casting. Instead of just turning this into `-> ()`, remove the
return type altogether, and add some asserts to prevent types of this
kind from being accidentally generated.
The `VK_KHR_ray_query` extension has no functions and this safe wrapper
(specifically to re-wrap functions) was added by accident (by me).
To prevent confusion, remove it before a new crate version is released.
Applications can easily access the name (which is the only useful thing
reexported here) from `ash::vk::extensions:KhrRayQueryFn::name()`.
In rust references to DSTs (Dynamically Sized Types) like slices and
trait objects are 16-bytes instead of 8 (leaking into the next parameter
of a function call). The static-sized array generated here has its size
known beforehand and will not suffer from this issue [1], but might be
confusing for future readers/authors: convert it to a raw pointer just
to be safe.
[1]: https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=88acb9736455f7262ecf4af2077f3a59
The API for vkCmdTraceRaysKHR mandates a single non-null pointer per SBT
region to a VkStridedDeviceAddressRegionKHR. While providing more than
one such region isn't harmful, passing a slice of length 0 will cause
reads in uninitialized memory and undefined behaviour.
Converting these parameters from slices to references rids the
unnecessary confusion and prevents zero regions from being passed.
