While this function is already marked `unsafe` to represent cases where
an invalid pointer might be dereferenced, it should at least be obvious
to the caller that there is a real chance for `NULL` pointers in these
`CStr` getters, which will now be returned as `None`. This function
won't be used in `Debug` now as the dereference operation is still
`unsafe`.
The `_as_c_str()` getters for static arrays is left untouched, as the
data is read directly from the known-valid struct here.
Upstream Vulkan is okay with the request to annotate static arrays with
a `len="structField"` annotation when the size of the static arrary
is bounded by a value at runtime. This allows us to generate more
convenient builder functions that copy slices into the target "builder"
struct while _also_ updating the length, rather than forcing the caller
to move an array of the desired length with zeroed elements and setting
the length field separately.
In addition provide a safe getter (and use it in the `Debug`
implementation) to return a slice view containing only valid items
per the length field. As with strings this is only possible for
static-sized arrays as we can never safely dereference a random pointer.
Rust 1.75 has once again gotten a bit more complete/strict when
linting code. `.get(0)` is now recommended to be replaced with
`.first()`, and needless glob reexports are equally denied (the modules
in question either contain macros which are already reexported via
`#[macro_export]`, or contain `impl` blocks exclusively which cannot be
referred to as item paths either).
All structs are marked as `Copy`, and builders move `self` for a
convenient builder pattern directly on `default()` (using `&mut`
requires requires first keeping the instance alive in a `let` binding).
This however leads to builder functions accidentally moving a copy of
`self`, mutating it, and dropping the result directly when the caller
did not consume the returned value in ad-hoc field updates, in turn
leaving the author confused why their code compiles without warnings
while the struct was not updated.
Annotating all Vulkan structs with `#[must_use]` should at least give
them an idea why.
Certain structs contain sized character arrays that are converted to
`CStr` for convenient accss to the user and our `Debug` implementation
using unsafe `CStr::from_ptr(...as_ptr())`. There is no need to
round-trip to a pointer and possibly read out of bounds if the
NUL-terminator index (string length) is instead searched for by the
newly stabilized `CStr::from_bytes_until_nul()` fn since Rust 1.69
(which panics if no NUL-terminator is found before the end of the
slice).
Unfortunately `unsafe` is still needed to cast the array from a `c_char`
(`i8` on most platforms) to `u8`, which is what `from_bytes_until_nul()`
accepts.
In essence this builder function needs to adhere to two rules:
1. No ref-after-free: the slice must outlive (uses of) the builder
object;
2. No aliasing: the slice cannot be (im)mutably used while it is mutably
borrowed within a live builder object.
These two rules have been tested and are satisfied by the given builder
implementation. Without this change `timings` seems to be borrowing
itself, hence is not allowed to be used after it has been temporarily
mutably borrowed inside the builder, even after that builder was
dropped. Thus defeating the purpose of this "getter" API via a struct.
Without the `.cast()`, because mutable raw pointers are invariant
(i.e. there is no subtyping relationship) the compiler complains about
requiring `self` to outlive `timings` instead, which does not satisfy
the two rules above.
It is a common operation to read and write NUL-terminated C string in
the Vulkan API, yet the only helpers for that were thus far open-coded
in the `Debug` printing implementations.
Move them to separate functions that are exposed to the user, in hopes
of helping them no longer misunderstand NUL-terminated strings (see
e.g. #830).
Important to note is that the array-copy for a static-sized `c_char`
array has also been replaced with a `CStr` wrapper: this forces the user
and our implementation to have a NUL-terminator at the end of the string,
and the setter returns `Err()` when the given `CStr (with NUL-terminator)
is too large for the static-sized array it has to be written to.
* Update Vulkan-Headers to 1.3.270
* Update Vulkan-Headers to 1.3.271
* extensions/nv/low_latency2: Support extension revision 2
Upon request the VK_NV_low_latency2 spec and API has been updated to move
the count pointer from the `vkGetLatencyTimingsNV()` function to
the `vkGetLatencyMarkerInfoNV` struct where the array pointer already
resided.
This got uncovered when it was realized that the `latency_marker_info`
argument isn't an array at all (which the original design of this
extension suggested), but a pointer to a single struct that _contains_
a pointer to an array, with the length passed as a separate argument to
the function instead.
The move of this count argument to a struct field - together with proper
array length annotations - gets our generator to automatically emit a
setter based on a slice argument.
[Dependabot complains] that:
the binary target name `examples` is forbidden, it conflicts with with cargo's build directory names
And fails to provide dependency upgrades for Rust code. Fix that by
renaming the folder and crate to `ash-examples`.
[Dependabot complains]: https://github.com/ash-rs/ash/network/updates/748770724
This parameter is not only used for the length of `pImageInfo`,
`pBufferInfo` or `pTexelBufferView`, but also matching the value
of `dataSize` when `VkWriteDescriptorSetInlineUniformBlock` is
appended in `pNext`, or the value of `accelerationStructureCount`
when `VkWriteDescriptorSetAccelerationStructureKHR` is in `pNext`.
Having the count setter directly avaialble makes builder code more
natural, instead of having to use a `mut` variable and manually assign
`.descriptor_count = xx.len();` afterwards.
https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkWriteDescriptorSet.html
* generator: Add many missing lifetime parameters
* Globally find-replace common patterns that need a `<'_>` lifetime annotation
perl -pi -E "s/(&(mut )?\[?vk::(?\!\w+(V1_\d|Fn|<))\w+)/\$1<'_>/" **/*.{rs,md}
* generator: Include aliased types in `has_lifetime` lookup table
* Manually revert wrong find-replace lifetimes
* Resolve lint warnings for `deprecated_in_future`, `rust_2018_idioms` and `unused_qualifications`
These are 3 non-default lints that cause a lot of violations in this
project that are sensible to resolve, and reduce noise when
test-including a local `ash` checkout in other projects that have
stricter lint setups.
* CI: Cross-lint for Mac, iOS and Windows
We have some conditional code specific to Mac and iOS which is currently
untested in the CI, allowing non-compiling code in PRs like #795 to go
unnoticed.
* Fix new clippy lints
* Update Vulkan-Headers to 1.3.255
* Update Vulkan-Headers to 1.3.257
* Update Vulkan-Headers to 1.3.258
* Update Vulkan-Headers to 1.3.259
* Update Vulkan-Headers to 1.3.260
* Update Vulkan-Headers to 1.3.252
* Update Vulkan-Headers to 1.3.253
* Update Vulkan-Headers to 1.3.254
* vk/platform_types: Add `_screen_buffer` type for QNX
* Update Vulkan-Headers to 1.3.247
* Update Vulkan-Headers to 1.3.248
* Update Vulkan-Headers to 1.3.249
* Update Vulkan-Headers to 1.3.250
* Update Vulkan-Headers to 1.3.251
Generate templated builder setters for fields taking an `objecttype`
We already do this for hand-written extension functions but can now also
implement it for setters since `vk_parse` fields are available within
the builder generator code: when a field refers to another field for
setting its `objecttype`, that `VkObjectType` field setter is omitted
and instead assigned when the object is set, based on a type generic
that implements the `Handle` trait instead of an untyped `u64`.
These functions don't contribute anything and should be removed to clean
up the `features` and `extensions` files, while now also not showing in
the documentation anymore. The structs remain in place for associated
constants but are replaced with true unit-like structs (no curly
brackets anymore), and unneeded `unsafe impl Send/Sync` are removed as
well.
As these `load()` functions have been removed from the empty
feature-levels on `Entry` and `Device` as well, rather than
instantiating the unit structs and returning those the fields and
`fp_vX_X()` getters have been removed entirely.
* Expose `FramebufferCreateInfo::attachment_count` builder for `IMAGELESS`
Don't omit the `attachment_count()` builder method, because it is valid
to set the number of attachments without providing attachments in the
`IMAGELESS` case.
Also change the generator array lookup to use the name of the count
field that is allowed to have a builder method, rather than the name of
the field that would use this as `len` field and hence cause it to be
skipped.
* Clean up clones
Some users are confused by seeing wildly different output after running
the generator, which is simply solved by running `rustfmt`. As this is
both confusing and "somewhat" slow, invoke `rustfmt` directly within the
generator by piping string contents through it before redirecting to
disk. This not only makes the output consistent, it is the fastest way
to reformat generator changes by omitting the round-trip to disk
entirely, nor having `rustfmt` recursively go through the workspace and
all files (including those that are not generated).
On a many-core machine these times are a bit skewed, but I want to
include them to prove the "speed" point nevertheless, even if simplicity
and consistency is the main reason to make this change:
Before:
time ./target/debug/generator && time cargo fmt --all
./target/debug/generator 3.51s user 1.25s system 99% cpu 4.769 total
cargo fmt --all 0.79s user 0.06s system 99% cpu 0.853 total
After:
time ./target/debug/generator
./target/debug/generator 4.51s user 0.41s system 99% cpu 4.931 total
Turns out we were doing the wrong thing for the right reason: the
`aliases` here aren't `vk.xml` aliases: they are renames. When
generating function pointers for extensions, a list of command
_definitions_ is collected, which can only ever be "root" `command`s.
Extensions typically reference stabilized `command`s under an alias with
the vendor tag suffixed, which the `Fn` struct field name is renamed to
using this `aliases` - now replaced with `rename_commands` - list, while
generating the rest of the "function pointer" command bits using the
"root" `command` (as this mostly pertains the parameters and return
type). With that explanation it becomes clear why
`generate_extension_commands()` was creating an "alias" mapping from
stabilized name to vendor-suffixed extension name, and calls
`generate_function_pointers()` with that mapping - and a list of
stabilized/root `command`s - rather than passing `cmd_aliases` directly.
(This `cmd_aliases` list exists because the rename always happens in the
root `<commands>` element: extensions then `<require>` the aliased
rather than the stabilized name, so the base for this alias is found
first to look up the base command, and then stored in `rename_commands`
to rename it back to the aliased name).
With improved clarity we can now also borrow the name strings rather
than cloning them in many places.
* Update Vulkan-Headers to 1.3.239
* Update Vulkan-Headers to 1.3.240
* Upgrade to `bindgen 0.63` and `vk-parse 0.9`
Updates cause no semantic changes in usage nor generated output.
* generator: Support new `deprecated` attribute
* Update Vulkan-Headers to 1.3.241
* generator: Emit `#[deprecated]` annotation for type members (struct fields)
* Update Vulkan-Headers to 1.3.242
* Update Vulkan-Headers to 1.3.243
* Update Vulkan-Headers to 1.3.244
For the upcoming `api` attribute in `vk.xml` commands also need to be
processed through `vk-parse` which has support for all the new
attributes, while `vkxml` is deprecated and completely untouched for
years. This conversion unfortunately requires whipping up yet another
quick-and-dirty `nom` parser of a specific subset of C used in `vk.xml`
to describe parameter signatures. This PR shows that conversion is
complete and provides no accidental semantic differences.
Also update `vk-parse` to `0.9` which contains a new `code` field on
`CommandParam` (`<param>` element) to be able to inspect the code
signature of individual parameters rather than parsing them out of (and
matching them back to `vk-parse`'s `params` array!) the `<command>`
/ `CommandDefinition` as a whole:
https://github.com/krolli/vk-parse/issues/25#issuecomment-1246330001615ffb69eb
`CStr::from_bytes_with_nul_unchecked` is `const`-stable since Rust 1.59
which is already required for `ash` so it is high time to finally turn
these inlined `name()` functions into associated constants (which is a
breaking change in itself that cannot be backported).
For upcoming `vk.xml` features (the new `api` attribute) some of our
codegen has to be converted to work on `vk-parse` types to make this
ergonomic (and there's a longstanding plan of factoring out `vkxml`
regardless). Start with converting the `#define` code and showcasing
that it does not affect the output (beyond removing the unneeded
edgecase for `VK_HEADER_VERSION` resulting in a doc link).
An upcoming extension will ship with an untyped `pCode` member (`void
*`) including a valid `len` field pointing to a `codeSize` field rather
than obscure Latex math and a `/4` expression in `altlen`. Limit the
scope of our workaround for that SPIR-V-specific `pCode` field to
`VkShaderModuleCreateInfo`.
Rustdoc since 1.66 points out that `<<ref>>` is malformed HTML, and the
resulting `<<devsandqueues-lost-device>>` isn't very helpful to users.
Convert it to the relevant link in both documentation and `Result`
`Display` to solve both issues at once.
It is unlikely that disabled, reserved extensions (without naming
whatsoever) are used through Ash bindings generated from Vulkan-Headers
releases, and are best ignored to reduce diff noise and spurious issues
[1] with unfinished extension definitions.
This approach matches what is defined in the registry spec for
`supported="disabled"` [2]:
use `supported="disabled"` to indicate this extension should never
be processed.
[1]: https://github.com/KhronosGroup/Vulkan-Docs/issues/1549
[2]: b4e8cd820b/registry.txt (L1302-L1306)
* Update Vulkan-Headers to 1.3.229
* Update Vulkan-Headers to 1.3.230
* Update Vulkan-Headers to 1.3.231
* Update Vulkan-Headers to 1.3.232
* Update Vulkan-Headers to 1.3.233
* Update Vulkan-Headers to 1.3.235
* README: Document experimental Vulkan Video bindings being semver-exempt
`.cast()` allows changing the pointer type without hiding (accidental)
mutability changes (noting that `*mut` still coerces to `*.const`).
For mutability changes Rust 1.65 included `cast_mut()` and
`cast_const()`, but those would bump our MSRV too eagerly for now.
Prepare the generator for more struct fields that have nested "dynamic
arrays" with a hardcoded size of `1` (effectively arrays with pointers
to single objects) in `vk.xml`s `len` attribute. These structs are
introduced by `VK_EXT_opacity_micromap` in 1.3.230.
* Update Vulkan-Headers to 1.3.220
* Update Vulkan-Headers to 1.3.221
* Update Vulkan-Headers to 1.3.222
* Update Vulkan-Headers to 1.3.223
* Update Vulkan-Headers to 1.3.224
* Update Vulkan-Headers to 1.3.225
* Update Vulkan-Headers to 1.3.226
* Update Vulkan-Headers to 1.3.227
* Update Vulkan-Headers to 1.3.228
* ash: Add `const STRUCTURE_TYPE` to all Vulkan structures for matching with `match_struct!` macro
In Vulkan layers extracing a structure based on its `s_type` is a common
operation, but comparing against an enum value and subsequently casting
to the right type is verbose and error-prone.
By generating a `const STRUCTURE_TYPE` with the given value for every
Vulkan structure it becomes possible to implement a macro that abstracts
this logic away in a safer way.
* generator: Reuse `HasStructureType::STRUCTURE_TYPE` in `s_type` initializer
* Update Vulkan-Headers to 1.3.212
* Update Vulkan-Headers to 1.3.213
* Update Vulkan-Headers to 1.3.214
* Update Vulkan-Headers to 1.3.215
* Update Vulkan-Headers to 1.3.216
* Update Vulkan-Headers to 1.3.217
* Update Vulkan-Headers to 1.3.218
* Update Vulkan-Headers to 1.3.219
* Changelog: reorder entries chronologically based on PR ID
`_` as prefix is intended for unused variables and bindings; it should
be used in suffix position when intending to prevent a clash with a
keyword instead.
