Much like `platform_types.rs` and `vk.rs` before, there is no need to
generate this file as its contents are completely static. This allows
direct editing of the file without realizing that a copy lives in the
generator - and will overwrite `macros.rs` when the generator is being
run.
Originally introduced in [#489] this inserts the array-length equality
check everywhere else: in the supposedly invalid and inexistant event
where Vulkan suddenly returns less items (`count` has been modified)
than were originally queried through respective `_len()` functions (or
more likely: a slice of invalid length passed by the user) and some
elements at the end of the slice are left uninitialized, panic.
Wherever there is valid concern or possibility for this to happen - or
to circumvent assertions and panics altogether - mutable references to
mutable slices should be passed allowing the length to be promptly
updated.
[#489]: https://github.com/MaikKlein/ash/pull/489#discussion_r753020089
When the misleading `all()` function was removed in #478 it also made
all color components for `ColorComponentFlags` significantly more
verbose to write, see #536.
These allocations and runtime assertions can all be replaced with a
`CStr` directly wrapping a binary-string literal, as long as it is
null-terminated.
Following the changes in a053c6a ("Remove unnecessary CString allocation
when loading functions (#379)") this addresses the remainder of string
allocations in manual extension loading code.
With more and more features being added to `ash`, now seems to be the
right time to make sure the crate is clean of clippy warnings when
building without any features in addition to building with the deafult
set of features.
This name is emitted by the generator and already known to not contain
any null-characters: replace the runtime iteration+comparison (hidden
behind `from_bytes_with_nul`) and `.expect()` panic with an `unsafe`
"cast" through `from_bytes_with_nul_unchecked`, just like the
function-pointer loaders.
On platforms like Android strings use `u8` as character-type instead of
`i8` - using the appropriate `c_char` type hides this discrepancy and
allows the examples to compile for all platforms.
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`.
