Manual code files usually see extra documentation lines added with
`///`, making for a rather unpleasant (source code) reading experience
when mixed with a link wrapped in `#[doc]`. This is just a copy-paste
remnant from autogenerated code (`quote` macro converts `///` to
`#[doc]`) and can easily be omitted in manual code.
Broken links that snuck in (most recently in #530 and #537) while the
CI was not testing the documentation have also been corrected, to allow
it to succeed again (and to have proper docs in the first place).
These two conversions occur all the time in Vulkan applications. For
example, Extent2D -> Extent3D occurs whenever you need to make an image
the same size as a surface and Extent2D -> Rect2D occurs whenever you
fill out a scissors or render area from a surface resolution.
Co-authored-by: Steve Wooster <s.f.m.wooster@gmail.com>
And drop the deprecated =/- markdown syntax from our readme: this is
analogous to #/## for a h1/h2 header, instead of defining a title and
(usually smaller font) subtitle or description.
This extension can be used to correlate timestamps on the GPU timeline
(`vkCmdWriteTimestamp`, `vkCmdWriteTimestamp2KHR`) to the CPU timeline
(ie. `CLOCK_MONOTONIC` and friends).
`raw-window-handle 0.3.4` was pushed as a "semver-trick-like" patch
release, implementing the `0.3` trait for the `0.4` crate release [74].
This allows `ash-window` as a window-handle "consumer" crate to accept
both `0.3` and `0.4` handles from consumer crates simultaneously. To
ensure this patch release is available even when users omit regular
`cargo update` or build with `-Z minimal-versions`, set the minimal
patch version in `Cargo.toml` to it.
[74]: https://github.com/rust-windowing/raw-window-handle/pull/74
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.
