Vulkan-Hpp has several configurable options and features for consumer projects. These are exposed as the following compiler macros, which be defined in a build system, or in the command-line invocation of a compiler.
VULKAN_HPP_ASSERTVULKAN_HPP_ASSERT_ON_RESULTVULKAN_HPP_DEFAULT_DISPATCHERVULKAN_HPP_DEFAULT_DISPATCHER_TYPEVULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGEVULKAN_HPP_DISABLE_ENHANCED_MODEVULKAN_HPP_DISPATCH_LOADER_DYNAMICVULKAN_HPP_DISPATCH_LOADER_DYNAMIC_TYPEVULKAN_HPP_DISPATCH_LOADER_STATIC_TYPEVULKAN_HPP_ENABLE_DYNAMIC_LOADER_TOOLVULKAN_HPP_EXPECTEDVULKAN_HPP_FLAGS_MASK_TYPE_AS_PUBLICVULKAN_HPP_HANDLE_ERROR_OUT_OF_DATE_AS_SUCCESSVULKAN_HPP_HANDLES_MOVE_EXCHANGEVULKAN_HPP_HASH_COMBINEVULKAN_HPP_INLINEVULKAN_HPP_NAMESPACEVULKAN_HPP_NO_CONSTRUCTORSVULKAN_HPP_NO_EXCEPTIONSVULKAN_HPP_NO_NODISCARD_WARNINGSVULKAN_HPP_NO_SETTERSVULKAN_HPP_NO_SMART_HANDLEVULKAN_HPP_NO_SPACESHIP_OPERATORVULKAN_HPP_NO_TO_STRINGVULKAN_HPP_NO_WIN32_PROTOTYPESVULKAN_HPP_RAII_NO_EXCEPTIONSVULKAN_HPP_SMART_HANDLE_IMPLICIT_CASTVULKAN_HPP_STORAGE_APIVULKAN_HPP_TYPESAFE_CONVERSIONVULKAN_HPP_UNEXPECTEDVULKAN_HPP_USE_REFLECTVULKAN_HPP_USE_STD_EXPECTED
At various places in vulkan.hpp an assertion statement is used. By default, the standard assert funtions from <cassert> is called. By defining VULKAN_HPP_ASSERT before including vulkan.hpp, you can change that to any function with the very same interface.
If there are no exceptions enabled (see VULKAN_HPP_NO_EXCEPTIONS), an assertion statement checks for a valid success code returned from every vulkan call. By default, this is the very same assert function as defined by VULKAN_HPP_ASSERT, but by defining VULKAN_HPP_ASSERT_ON_RESULT you can replace just those assertions with your own function, using the very same interface.
Every vk-function gets a Dispatcher as its very last argument, which defaults to VULKAN_HPP_DEFAULT_DISPATCHER. If VULKAN_HPP_DISPATCH_LOADER_DYNAMIC is defined to be 1, it is vk::detail::defaultDispatchLoaderDynamic. This in turn is the dispatcher instance, which is defined by VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE, which has to be used exactly once in your sources. If, on the other hand, VULKAN_HPP_DISPATCH_LOADER_DYNAMIC is defined to something different from 1, VULKAN_HPP_DEFAULT_DISPATCHER is set to be vk::detail::DispatchLoaderStatic().
You can use your own default dispatcher by setting VULKAN_HPP_DEFAULT_DISPATCHER to an object that provides the same API. If you explicitly set VULKAN_HPP_DEFAULT_DISPATCHER, you need to set VULKAN_HPP_DEFAULT_DISPATCHER_TYPE accordingly as well.
This names the default dispatcher type, as specified by VULKAN_HPP_DEFAULT_DISPATCHER. Per default, it is VULKAN_HPP_DISPATCH_LOADER_DYNAMIC_TYPE or VULKAN_HPP_DISPATCH_LOADER_STATIC_TYPE, depending on VULKAN_HPP_DISPATCH_LOADER_DYNAMIC being 1 or not 1, respectively. If you explicitly set VULKAN_HPP_DEFAULT_DISPATCHER, you need to set VULKAN_HPP_DEFAULT_DISPATCHER_TYPE accordingly as well.
If you have not defined your own VULKAN_HPP_DEFAULT_DISPATCHER, and have VULKAN_HPP_DISPATCH_LOADER_DYNAMIC defined to be 1 (the default), you need to have the macro VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE exactly once in any of your source files to provide storage for that default dispatcher. VULKAN_HPP_STORAGE_API then controls the import/export status of that default dispatcher.
Note
The C++ named module declares its own storage for the dynamic dispatcher, so this macro is not needed.
When this is defined before including vulkan.hpp, you essentially disable all enhanced functionality. All you then get is:
- improved compile time error detection, via scoped enums;
- usage of the helper class
vk::Flagsfor bitmasks; - wrapper structs for all vulkan structs providing default initialization;
- the helper class
vk::StructureChainfor compile-time construction of structure chains.
If this is not defined, you additionally get:
- enhanced versions of the commands (consuming
vk::ArrayProxy<>), simplifying handling of array data; returning requested data; throwing exceptions on errors (as long asVULKAN_HPP_NO_EXCEPTIONSis not defined); - enhanced structure constructors (as long as
VULKAN_HPP_NO_STRUCT_CONSTRUCTORSis not defined) (consumingvk::ArrayProxyNoTemporaries<>); - enhanced setter functions on some members of structs (consuming
vk::ArrayProxyNoTemporaries<>); - the helper classes
vk::ArrayProxy<>andvk::ArrayProxyNoTemporaries<> - all the RAII-stuff in
vulkan_raii.hpp
This either selects the dynamic (when it's 1) or the static (when it's not 1) DispatchLoader as the default one, as long as it's not explicitly specified by VULKAN_HPP_DEFAULT_DISPATCHER. By default, this is defined to be 1 if VK_NO_PROTOTYPES is defined, otherwise 0.
The type of the dynamic dispatch loader. By default, it's vk::detail::DispatchLoaderDynamic. You can define this before including vulkan.hpp to use your own dynamic dispatcher.
The type of the static dispatch loader. By default, it's vk::detail::DispatchLoaderStatic. You can define this before including vulkan.hpp to use your own static dispatcher.
By default, a little helper class vk::detail::DynamicLoader is used to dynamically load the vulkan library. If you set it to something different than 1 before including vulkan.hpp, this helper is not available, and you need to explicitly provide your own loader type for the function vk::detail::DispatchLoaderDynamic::init().
When this is not externally defined and VULKAN_HPP_CPP_VERSION is at least 23, VULKAN_HPP_EXPECTED is defined to be std::expected, and VULKAN_HPP_UNEXPECTED is defined to be std::unexpected.
By default, the member m_mask of the Flags class template is private. This is to prevent accidentally setting a Flags with some inappropriate value. But it also prevents using a Flags, or a structure holding a Flags, to be used as a non-type template parameter. If you really need that functionality, and accept the reduced security, you can use this define to change the access specifier for m_mask from private to public, which allows using a Flags as a non-type template parameter.
By default, VK_ERROR_OUT_OF_DATE_KHR is an error code. To prevent throwing an exception or, in case exceptions are turned off via VULKAN_HPP_NO_EXCEPTIONS, firing an assertion on this return value, you can define VULKAN_HPP_HANDLE_ERROR_OUT_OF_DATE_AS_SUCCESS. VK_ERROR_OUT_OF_DATE_KHR will then be handled like a success code.
This define can be used to enable m_handle = exchange( rhs.m_handle, {} ) in move constructors of Vulkan-Hpp handles, which default-initializes the rhs underlying value. By default Vulkan-Hpp handles behave like trivial types -- move constructors copying value.
This define can be used to specify your own hash combiner function. In order to determine the hash of a vk-structure, the hashes of the members of that struct are to be combined. This is done by this define, which by default is identical to what the function boost::hash_combine() does. It gets the type of the to-be-combined value, the seed, which is the combined value up to that point, and finally the to-be-combined value. This hash calculation determines a "shallow" hash, as it takes the hashes of any pointer in a structure, and not the hash of a pointed-to value.
This is set to be the compiler-dependent attribute used to mark functions as inline. If your compiler happens to need some different attribute, you can set this define accordingly before including vulkan.hpp.
By default, the namespace used with vulkan.hpp is vk. By defining VULKAN_HPP_NAMESPACE before including vulkan.hpp, you can adjust this.
With C++20, designated initializers are available. Their use requires the absence of any user-defined constructors. Define VULKAN_HPP_NO_CONSTRUCTORS to remove constructors from structs and unions.
When a vulkan function returns an error code that is not specified to be a success code, an exception is thrown unless VULKAN_HPP_NO_EXCEPTIONS is defined before including vulkan.hpp.
With C++17, all vk-functions returning something are declared with the attribute [[nodiscard]]. This can be removed by defining VULKAN_HPP_NO_NODISCARD_WARNINGS before including vulkan.hpp.
By defining VULKAN_HPP_NO_SETTERS before including vulkan.hpp, setter member functions will not be available within structs and unions. Modifying their data members will then only be possible via direct assignment.
By defining VULKAN_HPP_NO_SMART_HANDLE before including vulkan.hpp, the helper class vk::UniqueHandle and all the unique handle types are not available.
With C++20, the so-called spaceship-operator <=> is introduced. If that operator is supported, all the structs and classes in vulkan.hpp use the default implementation of it. As currently some implementations of this operator are very slow, and others seem to be incomplete, by defining VULKAN_HPP_NO_SPACESHIP_OPERATOR before including vulkan.hpp you can remove that operator from those structs and classes.
By default, the file vulkan_to_string.hpp is included by vulkan.hpp and provides functions vk::to_string for enums and bitmasks. If you don't need those functions, you can define VULKAN_HPP_NO_TO_STRING to prevent that inclusion. If you have certain files where you want to use those functions nevertheless, you can explicitly include vulkan_to_string.hpp there.
By default, if VULKAN_HPP_ENABLE_DYNAMIC_LOADER_TOOL is enabled on Win32, vulkan.hpp declares HINSTANCE, LoadLibraryA, and other required symbols. It could cause conflicts with the Windows.h alternatives, such as WindowsHModular.
With this define, you can disable these declarations, but you will have to declare them before the vulkan.hpp is included.
If both, VULKAN_HPP_NO_EXCEPTIONS and VULKAN_HPP_EXPECTED are defined, the vk::raii-classes don't throw exceptions. That is, the actual constructors are not available, but the creation-functions must be used. For more details have a look at the vk_raii_ProgrammingGuide.md.
Even though vk::UniqueHandle and vk::SharedHandle are semantically close to pointers, an implicit cast operator to the underlying vk::Handle might be handy. You can add that implicit cast operator by defining VULKAN_HPP_SMART_HANDLE_IMPLICIT_CAST.
With this define you can specify whether the vk::detail::DispatchLoaderDynamic is imported or exported (see VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE). If VULKAN_HPP_STORAGE_API is not defined externally, and VULKAN_HPP_STORAGE_SHARED is defined, depending on the VULKAN_HPP_STORAGE_SHARED_EXPORT being defined, VULKAN_HPP_STORAGE_API is either set to __declspec( dllexport ) (for MSVC) / __attribute__( ( visibility( "default" ) ) ) (for gcc or clang) or __declspec( dllimport ) (for MSVC), respectively. For other compilers, you might specify the corresponding storage by defining VULKAN_HPP_STORAGE_API on your own.
32-bit vulkan is not typesafe for non-dispatchable handles, so we don't allow copy constructors on this platform by default. To enable this feature on 32-bit platforms, #define VULKAN_HPP_TYPESAFE_CONVERSION 1. To disable this feature on 64-bit platforms, #define VULKAN_HPP_TYPESAFE_CONVERSION 0.
See VULKAN_HPP_EXPECTED.
Warning
This feature is extremely slow to compile (on the order of minutes), so only enable it if you absolutely need it.
With this define you can include a reflection mechanism on the vk-structures. It adds a function reflect that returns a tuple-version of the structure. That tuple then could easily be iterated. But at least for now, that feature takes lots of compile-time resources, so currently it is recommended to enable that feature only if you're willing to pay that price.
With this define, you can enable the use of std::expected for functions that return a value or a vk::Result. This requires C++23 or above.
See VULKAN_HPP_EXPECTED and VULKAN_HPP_UNEXPECTED for more details.