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);
-
instance
is the instance that the function pointer will be compatible with, orNULL
for commands not dependent on any instance. -
pName
is 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
instance
or 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,
vkGetInstanceProcAddr
can resolve itself with aNULL
instance 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::
apiVersion
when creating the instance will always return a valid function pointer. Core commands beyond that version which are supported by the implementation may either returnNULL
or a function pointer. If a function pointer is returned, it 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
device
or a child ofdevice
e.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);
-
pApiVersion
is 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);
-
pCreateInfo
is a pointer to a VkInstanceCreateInfo structure controlling creation of the instance. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pInstance
points 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkInstanceCreateFlagBits indicating the behavior of the instance. -
pApplicationInfo
isNULL
or a pointer to aVkApplicationInfo
structure. If notNULL
, this information helps implementations recognize behavior inherent to classes of applications. VkApplicationInfo is defined in detail below. -
enabledLayerCount
is the number of global layers to enable. -
ppEnabledLayerNames
is a pointer to an array ofenabledLayerCount
null-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. -
enabledExtensionCount
is the number of global extensions to enable. -
ppEnabledExtensionNames
is a pointer to an array ofenabledExtensionCount
null-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.
An application can add additional drivers by including the
VkDirectDriverLoadingListLUNARG struct to the pNext
element of
the VkInstanceCreateInfo
structure given to vkCreateInstance
.
Note
VkDirectDriverLoadingListLUNARG allows applications to ship drivers with themselves. Only drivers that are designed to work with it should be used, such as drivers that implement Vulkan in software or that implement Vulkan by translating it to a different API. Any driver that requires installation should not be used, such as hardware drivers. |
// 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_KHR
specifies 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
disabledValidationCheckCount
is the number of checks to disable. -
pDisabledValidationChecks
is 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_EXT
specifies that all validation checks are disabled. -
VK_VALIDATION_CHECK_SHADERS_EXT
specifies 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
enabledValidationFeatureCount
is the number of features to enable. -
pEnabledValidationFeatures
is a pointer to an array of VkValidationFeatureEnableEXT values specifying the validation features to be enabled. -
disabledValidationFeatureCount
is the number of features to disable. -
pDisabledValidationFeatures
is 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_EXT
specifies 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_EXT
specifies that the validation layers reserve a descriptor set binding slot for their own use. The layer reports a value for VkPhysicalDeviceLimits::maxBoundDescriptorSets
that 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_EXT
specifies 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_EXT
specifies that the layers will processdebugPrintfEXT
operations in shaders and send the resulting output to the debug callback. This feature is disabled by default. -
VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT
specifies 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_EXT
specifies that all validation checks are disabled. -
VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT
specifies that shader validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT
specifies that thread safety validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT
specifies that stateless parameter validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT
specifies that object lifetime validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT
specifies 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_EXT
specifies that protection against duplicate non-dispatchable object handles is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXT
specifies 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 VkDirectDriverLoadingListLUNARG
structure is defined as:
// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingListLUNARG {
VkStructureType sType;
void* pNext;
VkDirectDriverLoadingModeLUNARG mode;
uint32_t driverCount;
const VkDirectDriverLoadingInfoLUNARG* pDrivers;
} VkDirectDriverLoadingListLUNARG;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
mode
controls the mode in which to load the provided drivers. -
driverCount
is the number of driver manifest paths. -
pDrivers
is a pointer to an array ofdriverCount
VkDirectDriverLoadingInfoLUNARG structures.
When creating a Vulkan instance for which additional drivers are to be
included, add a VkDirectDriverLoadingListLUNARG
structure to the pNext
chain of the VkInstanceCreateInfo structure, and include in it the
list of VkDirectDriverLoadingInfoLUNARG
structures which contain the
information necessary to load additional drivers.
The VkDirectDriverLoadingInfoLUNARG
structure is defined as:
// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingInfoLUNARG {
VkStructureType sType;
void* pNext;
VkDirectDriverLoadingFlagsLUNARG flags;
PFN_vkGetInstanceProcAddrLUNARG pfnGetInstanceProcAddr;
} VkDirectDriverLoadingInfoLUNARG;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
pfnGetInstanceProcAddr
is a PFN_vkGetInstanceProcAddrLUNARG pointer to the driver vkGetInstanceProcAddr function.
Possible values of VkDirectDriverLoadingListLUNARG::mode
,
specifying the mode in which drivers are used, are:
// Provided by VK_LUNARG_direct_driver_loading
typedef enum VkDirectDriverLoadingModeLUNARG {
VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG = 0,
VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG = 1,
} VkDirectDriverLoadingModeLUNARG;
-
VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG
specifies that the provided drivers are used instead of the system-loaded drivers. -
VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG
specifies that the provided drivers are used in addition to the system-loaded drivers.
// Provided by VK_LUNARG_direct_driver_loading
typedef VkFlags VkDirectDriverLoadingFlagsLUNARG;
VkDirectDriverLoadingFlagsLUNARG
is a bitmask type for setting a mask,
but is currently reserved for future use.
The type of PFN_vkGetInstanceProcAddrLUNARG is:
// Provided by VK_LUNARG_direct_driver_loading
typedef PFN_vkVoidFunction (VKAPI_PTR *PFN_vkGetInstanceProcAddrLUNARG)(
VkInstance instance, const char* pName);
-
instance
is a VkInstance handle. -
pName
is the name of a Vulkan command.
This type is compatible with the type of a pointer to the
vkGetInstanceProcAddr command, but is used only to specify device
driver addresses in
VkDirectDriverLoadingInfoLUNARG::pfnGetInstanceProcAddr
.
Note
This type exists only because of limitations in the XML schema and
processing scripts, and its name may change in the future.
Ideally we would use 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;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pApplicationName
isNULL
or is a pointer to a null-terminated UTF-8 string containing the name of the application. -
applicationVersion
is an unsigned integer variable containing the developer-supplied version number of the application. -
pEngineName
isNULL
or is a pointer to a null-terminated UTF-8 string containing the name of the engine (if any) used to create the application. -
engineVersion
is an unsigned integer variable containing the developer-supplied version number of the engine used to create the application. -
apiVersion
must be the highest version of Vulkan that the application is designed to use, encoded as described in Version Numbers. The patch version number specified inapiVersion
is ignored when creating an instance object. The variant version of the instance must match that 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 |
Note
Providing a |
To destroy an instance, call:
// Provided by VK_VERSION_1_0
void vkDestroyInstance(
VkInstance instance,
const VkAllocationCallbacks* pAllocator);
-
instance
is the handle of the instance to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.