vks

Vulkan bindings and symbol loader for Rust

Latest supported Vulkan specification: 1.0.51 + all extensions

Usage

Vks is available on crates.io. Add this to your Cargo.toml:

[dependencies]
vks = "0.17"

Windows

On Windows, linking vks requires vulkan-1.lib, if the feature no_function_prototypes is not enabled. Make sure the environment variable VULKAN_SDK points to the root of the LunarG Vulkan SDK. This is the default, if you use the Vulkan SDK installer.

Cargo Features

Vks supports very fine grained compile-time configuration via Cargo features. The version of the core specification and the revision for each extension can be selected individually. Dependencies between available features are modelled as well. This means, selecting nothing but a single extension revision (i.e. via cargo build --no-default-features --features khr_wayland_surface_5) will still pull in the lowest core specification, that supported that extension (i.e. core_1_0_3), as well as possibly other dependencies (i.e. khr_surface_25).

The default feature will always select the latest fully supported core Vulkan specification as well as all extensions, that are supported and have been defined up to that point. Basically, default will select everything, except for features, which are incomplete and still in development.

no_function_prototypes Feature

Enabling this feature, will cause all function definitions to be omitted. Linking against Vulkan is not required in this case. This feature is especially useful, if you load Vulkan dynamically at runtime and don't need the function definitions anyway.

unstable_rust Feature

This feature is optional and not included in the default feature, because it requires a nightly version of the Rust compiler. The feature enables untagged_unions and struct_field_attributes.

When untagged_unions and struct_field_attributes become available in stable Rust, we will remove the current work-arounds and switch to what is now behind unstable_rust.

vk_* Features

All of these features select a specific core specification as well as all extensions, that were defined up to that point. Features in this category have the form vk_a_b_c, where a, b, and c refer to the Vulkan specification. For example, vk_1_0_32 will select the core Vulkan 1.0.32 specification and all extensions, that existed at that point. The earliest version that can be selected is 1.0.3 (via vk_1_0_3). The most recent version is selected by the default feature.

core_* Features

These features select only the core specification without any extensions. They have the same form and range of valid versions as the vk_* features, except for the core_ prefix. The earliest version that can be selected is 1.0.3 (via core_1_0_3). The most recent version is selected by the core feature.

Extension Features

Every extension maps to a Cargo feature by removing the VK_ prefix from its lowercase name. For example, the feature amd_negative_viewport_height corresponds to the extension VK_AMD_negative_viewport_height. Features that are formed this way, will always select the most recent extension revision, as well as the lowest compatible core specification (usually 1.0.3 via core_1_0_3) and possibly other dependencies.

Specific revisions can be selected by appending _x to the feature, where x is the desired revision. For example, ext_debug_report_3 selects revision 3 of VK_EXT_debug_report, instead of the newest revision.

Loader

Vks includes two convenience Vulkan symbol loaders: InstanceProcAddrLoader and DeviceProcAddrLoader. Both support all available core Vulkan functions including extension function pointers. The exact set of function pointers depends on the enabled Cargo features.

Supported Vulkan Specifications

• Latest: 1.0.51
• Earliest: 1.0.3

Every version in between is supported as well.

Supported Extensions

KHR Extensions

EXT Extensions

NV Extensions

IMG Extensions

AMD Extensions

NVX Extensions

NN Extensions

KHX Extensions

MVK Extensions

GOOGLE Extensions

License

Vks is licensed under the ISC license:

Copyright (c) 2017, Dennis Hamester <dennis.hamester@startmail.com>

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.