Instead of generating an impl block - together with "Generated from XXX"
doc - for every single item that extends an enum type, group all these
extensions together in a single `impl` block per extension per type.
This cuts down a couple thousand lines of repeated `impl T` and `#[doc]`
annotations, and makes the code more readable at the same time: it is
now possible to immediately see exactly all the constants that a certain
extension extends a type with.
Back when we were still trying to come up with sensible names for
"deprecated" aliases (initially introduced as self-supporting constants)
that don't adhere to the naming standard but only remain to exist for
backwards compatibility, some of these aliases would get the same name
as the enum constant they were aliasing, resulting in (compile-time)
conflicts.
Now that all those aliases are simply not generated anymore (end-users
should just pick the properly named variant) it is not necessary to
check for and prevent these conflicts on the generator side anymore.
`constants` is iterated twice here: once with a filter, the other time
without, and the results are zipped together. Besides being able to
simplify the entire execution to just one `iter()` without intermediary
iterators, removing `.zip()` makes it impossible for the results in both
iterators to get mismatched when the `filter` inevitably skips elements.
Fortunately no such cases seem to exist, or at least not that effect the
resulting generated code.
Some clippy lint long ago apparently suggested to explicitly specify a
type for all random generators in 8550683 ("Address all the clippy lints
(#233)"), so the `impl BuildHasher` trait was apparently passed as a
placeholder for the `RandomState` default that's selected.
This does not serve any purpose and that (likely bogus) clippy warning
no longer shows up, making it safe to remove the trait.
As per the readme `.build()` should only be called as late as possible,
and only if absolutely necessary; such cases include slices that are
passed directly to functions. More precisely, such build calls and the
creation of temporary slices should happen inside the same expression as
the function call to be sound and completely lifetime-checked.
This pattern of `&[my_builder.build()]` is however not possible when
constructing intermediary Vulkan objects that reference the slice. In
the first place this slice goes out of scope after the expression that
creates the Vulkan object, which is caught and disallowed by rustc
(unless this expression itself ends in `.build()`, which is completely
unsound as it makes rustc unable to validate this lifetime dependency).
In the second place - and as is most relevant for this patch that
removes `.build()` calls that were not surrounded by temporary slice
constructors - said expression drops the lifetime checks on anything
held by `my_builder` which _could_ go out of scope before the newly
constructed Vulkan object is used, resulting yet again in Undefined
Behaviour.
Fortunately, for slices of size 1 which are typical in Vulkan,
`std::slice::as_ref` exists which is analogous to taking a pointer to an
object and considering it an array of length 1 in C(++). This maintains
the lifetime through `Deref` and makes rustc able to fully check all
lifetimes and prevent unsound code.
Albeit improving overall consistency, the `&[my_builder.build()]`
pattern is not substituted in aforementioned Vulkan function-call
expressions as that is considered "extraneous" [1] and demonstrates the
various ways to safely construct Vulkan objects for the observant reader.
[1]: https://github.com/MaikKlein/ash/pull/506#discussion_r762630648
* extensions: Make naming and layout consistent across all extensions
breaking change:
- some extensions were exposing `instance()` instead of `device()`
includes:
- renaming function pointer member to `fns`
- moving `name()`, `fp(`), `device()`/`instance()` functions at end of file
- adding missing `device()`/`instance()` functions
see https://github.com/MaikKlein/ash/pull/493
* debug_marker: Remove unneeded `device` from `debug_marker_set_object_name()`
* extensions: Remove unneeded `instance` and `device` struct members and functions
* extensions: renamed all `fns` fields to `fp` to match `pub fn fp()` getter
vk.xml now contains the comment text "Backwards-compatible alias
containing a typo" which we can use to detect intentional renames,
without needing to specify explicit overrides/exceptions in the
generator anymore.
These deprecated constants exist for the sole reason of backwards
compatibility which Vulkan cannot permit itself to remove in the C
headers, but are unreasonable for crate authors to use anyway due to
their `#[deprecated]` annotation whose cargo-check warnings are easy to
fix by just using the non-deprecated variant instead. Furthermore, Ash
is still allowing itself to perform breaking changes in its releases
making this the perfect time to get rid of all these useless variants
and the generator support code that comes with it. No need to come up
with a "more proper" variant name if we don't generate those that
"intentionally" fail to adhere to the "enum variant name" specification
in the first place.
This naming was changed at the last resort across the other `_len()`
variant calls to be consistent, but the maintenance4 PR didn't have its
documentation updated (probably some rust-analyzer "rename symbol"
action).
Fixes: 50d58fd ("extensions: Add VK_KHR_maintenance4")
Of all the extensions calling get_instance_proc_addr only these two
remain that should use the "optimized" device-specific function
pointers, since all functions take the device as argument (a child of
the device such as a command buffer or queue is also possible, but not
applicable here) and may otherwise have to go through a dispatch
function [1].
Only VK_EXT_debug_utils remains where all but three of the functions are
device (or device-child) specific. This however requires the
autogenerated loader to be separated out into two stages (and debug
utils are generally initialized before creating a logical device),
making it worth to accept the dispatch function unless this extension
struct is split, too.
[1]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetDeviceProcAddr.html
Point the user in the right direction telling them where to get the
length of the mutable slice that has to passed in, and document that
these have to be default-initialized (so that `s_type` is set
appropriately) and `p_next` can optionally be set too.
The `all()` function only represents bitflags known in the core of
Vulkan; it omits all bits added by extensions making this function
unrepresentative and has hence been scheduled for removal for quite some
time to get rid of the confusion it causes.
Alternatively the generator could be taught to collect bitflags added by
extensions, but new extensions get added over time skewing available
values in ash versus the current driver/environment. This makes the
value from `all()` unreliable and fragile at best.
`-` and `-=` (`sub()` and `sub_assign()`) are also controversial by
nature since the underlying value represents an integer but the
implemented math uses bitwise operators. This is a confusing design
pattern and the caller better replaces their uses - if any at all - with
`foo &= !BAR`.
* Update Vulkan-Headers to 1.2.192
* Update Vulkan-Headers to 1.2.193
* Update Vulkan-Headers to 1.2.194
* Update Vulkan-Headers to 1.2.195
Includes the new VK_EXT_rgba10x6_formats, VK_KHR_format_feature_flags2
and VK_KHR_maintenance4 extensions.
* Update Vulkan-Headers to 1.2.196
Includes Vulkan-Headers fixup commit with the missing h265 encode
header.
* Update Vulkan-Headers to 1.2.197
* Update Vulkan-Headers to 1.2.198
`syn` has been updated to not remove the `_` again from negative
numbers, which previously disappeared in the 1.0 upgrade in 43b5058
("Upgrade proc_macro2/syn/quote to v1.0 (#351)").
See also https://github.com/dtolnay/syn/releases/tag/1.0.81:
Support arbitrary precision negative literal tokens on rustc 1.56+
* generator: Use `Self` instead of `$name` in macros
Saves a bit of unnecessary expansion inside the macro.
* Fix remaining violations of clippy::use_self in generated code
* generator: Remove unnecessary match on reference type
* ash: Exclude static `vk.rs` from the generator
Much like `platform_types.rs` `vk.rs` does not contain any generated
code that depends on `Vulkan-Headers`' `vk.xml`, making it easier to
just keep this file manually editable.
* Add Packed24_8 helper-type for constructing AS Instance bitfields
* Mark EntryCustom::new_custom as unsafe
Passing a badly-behaved `load` function can invoke undefined behavior.
* Document required feature for Entry
* Support linking Vulkan directly
This is the preferred pattern in most environments when an application
cannot function without Vulkan, as it saves the libloading dependency,
eliminates an error case, and makes the Vulkan dependency visible to
the OS.
* Rename libloading feature to "loaded"
* Link by default
* Guide users towards linking the loader directly
* Remove unnecessary error type
InstanceError::LoadError was never constructed.
* Unify entry types
Simplifies the interface and allows a bunch of code to become
monomorphic.
* Update Vulkan-Headers to 1.2.187; drop Video enum-variant edgecases
* Update Vulkan-Headers to 1.2.188
* generator: Improve support for pointers to static-sized arrays
Vulkan 1.2.188 removed the only occurence of `ename:`, which was our
heuristic to find a type that's a pointer to a static-sized array. It
is now replaced with a "normal" `latexmath:` expression, but should
still be dealt with appropriately.
Note that all `latexmath:` conditions have been removed, as these fields
should not be silently omitted. As of this Vulkan version only 3 exist,
and all have their own edge-case.
* Revert "Remove upstream-fixed vk_platform.h header path fallback"
This reverts commit 43dee26ec04dfd3871da8a11b624eaf9fbd16f3a.
Upstream is reverting back to inconsistent paths in [this commit] to
counter unintentional header `#include` changes on the C-side:
https://github.com/KhronosGroup/Vulkan-Docs/issues/1573
[this commit]: 8bde11cbd7
* generator: Remove unnecessary `-Iinclude/vulkan` directory
Every `#include` path (except `"vk_platform.h"`, see previous commit) is
relative to the `include/` directory or the current file, and does not
look for a path relative to `include/vulkan/`.
* Update Vulkan-Headers to 1.2.189
* Update Vulkan-Headers to 1.2.190
* Update Vulkan-Headers to 1.2.191
Fixes https://github.com/MaikKlein/ash/issues/354
`io::Read::read_exact` does not receive `MaybeUninit` memory and a trait
implementation can possibly read from our uninitialized vector without
`unsafe`, which is UB. As there is no proper solution to this problem
yet (see linked issue), our safest bet is to just take the perf-hit and
zero-initialize this vector.
* Update Vulkan-Headers to 1.2.176
* Update Vulkan-Headers to 1.2.177
* Update Vulkan-Headers to 1.2.178
This requires `len="null-terminated"` to be added to
`VkCuFunctionCreateInfoNVX::pName` in `vk.xml`.
* Update Vulkan-Headers to 1.2.179
* Update Vulkan-Headers to 1.2.181
Skipping 1.2.180 due to missing VkPipelineLayoutCreateFlagBits, which is
defined now.
* push_next and Extends traits are generated for all root structs.
root structs are now all structs that are extended by other structs!
root structs used to be all structs that don't extend any other structs.
* the root_structs local variable that is passed around is now a set of Ident (and no String).
fixes https://github.com/MaikKlein/ash/issues/229
