4. Initialization
Before using Vulkan, an application must initialize it by loading the
Vulkan commands, and creating a VkInstance object.
4.1. Command Function Pointers
Vulkan commands are not necessarily exposed by static linking on a platform. Commands to query function pointers for Vulkan commands are described below.
|
Note
When extensions are promoted or otherwise incorporated into another extension or Vulkan core version, command aliases may be included. Whilst the behavior of each command alias is identical, the behavior of retrieving each alias’s function pointer is not. A function pointer for a given alias can only be retrieved if the extension or version that introduced that alias is supported and enabled, irrespective of whether any other alias is available. |
Function pointers for all Vulkan commands can be obtained with the command:
// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetInstanceProcAddr(
VkInstance instance,
const char* pName);
-
instanceis the instance that the function pointer will be compatible with, orNULLfor commands not dependent on any instance. -
pNameis the name of the command to obtain.
vkGetInstanceProcAddr itself is obtained in a platform- and loader-
specific manner.
Typically, the loader library will export this command as a function symbol,
so applications can link against the loader library, or load it dynamically
and look up the symbol using platform-specific APIs.
The table below defines the various use cases for
vkGetInstanceProcAddr and expected return value (“fp” is “function
pointer”) for each case.
A valid returned function pointer (“fp”) must not be NULL.
The returned function pointer is of type PFN_vkVoidFunction, and must be cast to the type of the command being queried before use.
instance |
pName |
return value |
|---|---|---|
*1 |
|
undefined |
invalid non- |
*1 |
undefined |
|
global command2 |
fp |
|
fp5 |
|
instance |
fp |
|
instance |
core dispatchable command |
fp3 |
instance |
enabled instance extension dispatchable command for |
fp3 |
instance |
available device extension4 dispatchable command for |
fp3 |
any other case, not covered above |
|
|
- 1
-
"*" means any representable value for the parameter (including valid values, invalid values, and
NULL). - 2
-
The global commands are: vkEnumerateInstanceVersion, vkEnumerateInstanceExtensionProperties, vkEnumerateInstanceLayerProperties, and vkCreateInstance. Dispatchable commands are all other commands which are not global.
- 3
-
The returned function pointer must only be called with a dispatchable object (the first parameter) that is
instanceor a child ofinstance, e.g. VkInstance, VkPhysicalDevice, VkDevice, VkQueue, or VkCommandBuffer. - 4
-
An “available device extension” is a device extension supported by any physical device enumerated by
instance. - 5
-
Starting with Vulkan 1.2,
vkGetInstanceProcAddrcan resolve itself with aNULLinstance pointer.
In order to support systems with multiple Vulkan implementations, the
function pointers returned by vkGetInstanceProcAddr may point to
dispatch code that calls a different real implementation for different
VkDevice objects or their child objects.
The overhead of the internal dispatch for VkDevice objects can be
avoided by obtaining device-specific function pointers for any commands that
use a device or device-child object as their dispatchable object.
Such function pointers can be obtained with the command:
// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetDeviceProcAddr(
VkDevice device,
const char* pName);
The table below defines the various use cases for vkGetDeviceProcAddr
and expected return value (“fp” is “function pointer”) for each case.
A valid returned function pointer (“fp”) must not be NULL.
The returned function pointer is of type PFN_vkVoidFunction, and must
be cast to the type of the command being queried before use.
The function pointer must only be called with a dispatchable object (the
first parameter) that is device or a child of device.
device |
pName |
return value |
|---|---|---|
|
*1 |
undefined |
invalid device |
*1 |
undefined |
device |
|
undefined |
device |
requested core version2 device-level dispatchable command3 |
fp4 |
device |
enabled extension device-level dispatchable command3 |
fp4 |
any other case, not covered above |
|
|
- 1
-
"*" means any representable value for the parameter (including valid values, invalid values, and
NULL). - 2
-
Device-level commands which are part of the core version specified by VkApplicationInfo::
apiVersionwhen creating the instance will always return a valid function pointer. Core commands beyond that version which are supported by the implementation may either returnNULLor a function pointer, though the function pointer must not be called. - 3
-
In this function, device-level excludes all physical-device-level commands.
- 4
-
The returned function pointer must only be called with a dispatchable object (the first parameter) that is
deviceor a child ofdevicee.g. VkDevice, VkQueue, or VkCommandBuffer.
The definition of PFN_vkVoidFunction is:
// Provided by VK_VERSION_1_0
typedef void (VKAPI_PTR *PFN_vkVoidFunction)(void);
This type is returned from command function pointer queries, and must be cast to an actual command function pointer before use.
4.1.1. Extending Physical Device Core Functionality
New core physical-device-level functionality can be used when the physical-device version is greater than or equal to the version of Vulkan that added the new functionality. The Vulkan version supported by a physical device can be obtained by calling vkGetPhysicalDeviceProperties.
4.1.2. Extending Physical Device From Device Extensions
When the VK_KHR_get_physical_device_properties2 extension is
enabled,
or when both the instance and the physical-device versions are at least 1.1,
physical-device-level functionality of a device extension can be used with
a physical device if the corresponding extension is enumerated by
vkEnumerateDeviceExtensionProperties for that physical device, even
before a logical device has been created.
To obtain a function pointer for a physical-device-level command from a
device extension, an application can use vkGetInstanceProcAddr.
This function pointer may point to dispatch code, which calls a different
real implementation for different VkPhysicalDevice objects.
Applications must not use a VkPhysicalDevice in any command added by
an extension or core version that is not supported by that physical device.
Device extensions may define structures that can be added to the
pNext chain of physical-device-level commands.
4.2. Instances
There is no global state in Vulkan and all per-application state is stored
in a VkInstance object.
Creating a VkInstance object initializes the Vulkan library and allows
the application to pass information about itself to the implementation.
Instances are represented by VkInstance handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkInstance)
To query the version of instance-level functionality supported by the implementation, call:
// Provided by VK_VERSION_1_1
VkResult vkEnumerateInstanceVersion(
uint32_t* pApiVersion);
-
pApiVersionis a pointer to auint32_t, which is the version of Vulkan supported by instance-level functionality, encoded as described in Version Numbers.
|
Note
The intended behaviour of vkEnumerateInstanceVersion is that an
implementation should not need to perform memory allocations and should
unconditionally return |
To create an instance object, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateInstance(
const VkInstanceCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkInstance* pInstance);
-
pCreateInfois a pointer to a VkInstanceCreateInfo structure controlling creation of the instance. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pInstancepoints a VkInstance handle in which the resulting instance is returned.
vkCreateInstance verifies that the requested layers exist.
If not, vkCreateInstance will return VK_ERROR_LAYER_NOT_PRESENT.
Next vkCreateInstance verifies that the requested extensions are
supported (e.g. in the implementation or in any enabled instance layer) and
if any requested extension is not supported, vkCreateInstance must
return VK_ERROR_EXTENSION_NOT_PRESENT.
After verifying and enabling the instance layers and extensions the
VkInstance object is created and returned to the application.
If a requested extension is only supported by a layer, both the layer and
the extension need to be specified at vkCreateInstance time for the
creation to succeed.
The VkInstanceCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkInstanceCreateInfo {
VkStructureType sType;
const void* pNext;
VkInstanceCreateFlags flags;
const VkApplicationInfo* pApplicationInfo;
uint32_t enabledLayerCount;
const char* const* ppEnabledLayerNames;
uint32_t enabledExtensionCount;
const char* const* ppEnabledExtensionNames;
} VkInstanceCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkInstanceCreateFlagBits indicating the behavior of the instance. -
pApplicationInfoisNULLor a pointer to aVkApplicationInfostructure. If notNULL, this information helps implementations recognize behavior inherent to classes of applications. VkApplicationInfo is defined in detail below. -
enabledLayerCountis the number of global layers to enable. -
ppEnabledLayerNamesis a pointer to an array ofenabledLayerCountnull-terminated UTF-8 strings containing the names of layers to enable for the created instance. The layers are loaded in the order they are listed in this array, with the first array element being the closest to the application, and the last array element being the closest to the driver. See the Layers section for further details. -
enabledExtensionCountis the number of global extensions to enable. -
ppEnabledExtensionNamesis a pointer to an array ofenabledExtensionCountnull-terminated UTF-8 strings containing the names of extensions to enable.
To capture events that occur while creating or destroying an instance, an
application can link a
VkDebugReportCallbackCreateInfoEXT structure
or a
VkDebugUtilsMessengerCreateInfoEXT structure
to the pNext element of the VkInstanceCreateInfo structure given
to vkCreateInstance.
This callback is only valid for the duration of the vkCreateInstance
and the vkDestroyInstance call.
Use
vkCreateDebugReportCallbackEXT
or
vkCreateDebugUtilsMessengerEXT
to create persistent callback objects.
// Provided by VK_VERSION_1_0
typedef enum VkInstanceCreateFlagBits {
// Provided by VK_KHR_portability_enumeration
VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR = 0x00000001,
} VkInstanceCreateFlagBits;
-
VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHRspecifies that the instance will enumerate available Vulkan Portability-compliant physical devices and groups in addition to the Vulkan physical devices and groups that are enumerated by default.
// Provided by VK_VERSION_1_0
typedef VkFlags VkInstanceCreateFlags;
VkInstanceCreateFlags is a bitmask type for setting a mask of zero or
more VkInstanceCreateFlagBits.
When creating a Vulkan instance for which you wish to disable validation
checks, add a VkValidationFlagsEXT structure to the pNext chain
of the VkInstanceCreateInfo structure, specifying the checks to be
disabled.
// Provided by VK_EXT_validation_flags
typedef struct VkValidationFlagsEXT {
VkStructureType sType;
const void* pNext;
uint32_t disabledValidationCheckCount;
const VkValidationCheckEXT* pDisabledValidationChecks;
} VkValidationFlagsEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
disabledValidationCheckCountis the number of checks to disable. -
pDisabledValidationChecksis a pointer to an array of VkValidationCheckEXT values specifying the validation checks to be disabled.
Possible values of elements of the
VkValidationFlagsEXT::pDisabledValidationChecks array,
specifying validation checks to be disabled, are:
// Provided by VK_EXT_validation_flags
typedef enum VkValidationCheckEXT {
VK_VALIDATION_CHECK_ALL_EXT = 0,
VK_VALIDATION_CHECK_SHADERS_EXT = 1,
} VkValidationCheckEXT;
-
VK_VALIDATION_CHECK_ALL_EXTspecifies that all validation checks are disabled. -
VK_VALIDATION_CHECK_SHADERS_EXTspecifies that shader validation is disabled.
When creating a Vulkan instance for which you wish to enable or disable
specific validation features, add a VkValidationFeaturesEXT structure
to the pNext chain of the VkInstanceCreateInfo structure,
specifying the features to be enabled or disabled.
// Provided by VK_EXT_validation_features
typedef struct VkValidationFeaturesEXT {
VkStructureType sType;
const void* pNext;
uint32_t enabledValidationFeatureCount;
const VkValidationFeatureEnableEXT* pEnabledValidationFeatures;
uint32_t disabledValidationFeatureCount;
const VkValidationFeatureDisableEXT* pDisabledValidationFeatures;
} VkValidationFeaturesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
enabledValidationFeatureCountis the number of features to enable. -
pEnabledValidationFeaturesis a pointer to an array of VkValidationFeatureEnableEXT values specifying the validation features to be enabled. -
disabledValidationFeatureCountis the number of features to disable. -
pDisabledValidationFeaturesis a pointer to an array of VkValidationFeatureDisableEXT values specifying the validation features to be disabled.
Possible values of elements of the
VkValidationFeaturesEXT::pEnabledValidationFeatures array,
specifying validation features to be enabled, are:
// Provided by VK_EXT_validation_features
typedef enum VkValidationFeatureEnableEXT {
VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT = 0,
VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT = 1,
VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT = 2,
VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT = 3,
VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT = 4,
} VkValidationFeatureEnableEXT;
-
VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXTspecifies that GPU-assisted validation is enabled. Activating this feature instruments shader programs to generate additional diagnostic data. This feature is disabled by default. -
VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXTspecifies that the validation layers reserve a descriptor set binding slot for their own use. The layer reports a value for VkPhysicalDeviceLimits::maxBoundDescriptorSetsthat is one less than the value reported by the device. If the device supports the binding of only one descriptor set, the validation layer does not perform GPU-assisted validation. This feature is disabled by default. -
VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXTspecifies that Vulkan best-practices validation is enabled. Activating this feature enables the output of warnings related to common misuse of the API, but which are not explicitly prohibited by the specification. This feature is disabled by default. -
VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXTspecifies that the layers will processdebugPrintfEXToperations in shaders and send the resulting output to the debug callback. This feature is disabled by default. -
VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXTspecifies that Vulkan synchronization validation is enabled. This feature reports resource access conflicts due to missing or incorrect synchronization operations between actions (Draw, Copy, Dispatch, Blit) reading or writing the same regions of memory. This feature is disabled by default.
Possible values of elements of the
VkValidationFeaturesEXT::pDisabledValidationFeatures array,
specifying validation features to be disabled, are:
// Provided by VK_EXT_validation_features
typedef enum VkValidationFeatureDisableEXT {
VK_VALIDATION_FEATURE_DISABLE_ALL_EXT = 0,
VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT = 1,
VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT = 2,
VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT = 3,
VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT = 4,
VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT = 5,
VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT = 6,
VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXT = 7,
} VkValidationFeatureDisableEXT;
-
VK_VALIDATION_FEATURE_DISABLE_ALL_EXTspecifies that all validation checks are disabled. -
VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXTspecifies that shader validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXTspecifies that thread safety validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXTspecifies that stateless parameter validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXTspecifies that object lifetime validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXTspecifies that core validation checks are disabled. This feature is enabled by default. If this feature is disabled, the shader validation and GPU-assisted validation features are also disabled. -
VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXTspecifies that protection against duplicate non-dispatchable object handles is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXTspecifies that there will be no caching of shader validation results and every shader will be validated on every application execution. Shader validation caching is enabled by default.
|
Note
Disabling checks such as parameter validation and object lifetime validation prevents the reporting of error conditions that can cause other validation checks to behave incorrectly or crash. Some validation checks assume that their inputs are already valid and do not always revalidate them. |
|
Note
The |
The VkApplicationInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkApplicationInfo {
VkStructureType sType;
const void* pNext;
const char* pApplicationName;
uint32_t applicationVersion;
const char* pEngineName;
uint32_t engineVersion;
uint32_t apiVersion;
} VkApplicationInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pApplicationNameisNULLor is a pointer to a null-terminated UTF-8 string containing the name of the application. -
applicationVersionis an unsigned integer variable containing the developer-supplied version number of the application. -
pEngineNameisNULLor is a pointer to a null-terminated UTF-8 string containing the name of the engine (if any) used to create the application. -
engineVersionis an unsigned integer variable containing the developer-supplied version number of the engine used to create the application. -
apiVersionmust be the highest version of Vulkan that the application is designed to use, encoded as described in Version Numbers. The patch version number specified inapiVersionis ignored when creating an instance object. Only the major and minor versions of the instance must match those requested inapiVersion.
Vulkan 1.0 implementations were required to return
VK_ERROR_INCOMPATIBLE_DRIVER if apiVersion was larger than 1.0.
Implementations that support Vulkan 1.1 or later must not return
VK_ERROR_INCOMPATIBLE_DRIVER for any value of apiVersion.
|
Note
Because Vulkan 1.0 implementations may fail with
|
As long as the instance supports at least Vulkan 1.1, an application can use different versions of Vulkan with an instance than it does with a device or physical device.
|
Note
The Khronos validation layers will treat For example, if the instance supports Vulkan 1.1 and three physical devices
support Vulkan 1.0, Vulkan 1.1, and Vulkan 1.2, respectively, and if the
application sets
If we modify the above example so that the application sets |
Implicit layers must be disabled if they do not support a version at least
as high as apiVersion.
See the “Architecture of the Vulkan Loader
Interfaces” document for additional information.
|
Note
Providing a |
To destroy an instance, call:
// Provided by VK_VERSION_1_0
void vkDestroyInstance(
VkInstance instance,
const VkAllocationCallbacks* pAllocator);
-
instanceis the handle of the instance to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.