vkCreateInstance

vkCreateInstance is a Vulkan API function used to create a VkInstance object, the top-level handle that represents an application's connection to the Vulkan API and the global state for a Vulkan session. The VkInstance is required before any other Vulkan objects can be created, and it serves as the foundation for interacting with physical devices and creating logical devices.

The function signature is VkResult vkCreateInstance(const VkInstanceCreateInfo* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkInstance* pInstance). The pCreateInfo parameter points to a VkInstanceCreateInfo structure that describes the application information, enabled layers, and enabled extensions. The pAllocator parameter can be NULL or point to a custom allocator for host memory usage. The pInstance parameter receives the created VkInstance handle on success.

VkInstanceCreateInfo encapsulates several fields, including sType, pNext, flags, pApplicationInfo (a pointer to VkApplicationInfo, which can be NULL), enabledLayerCount and ppEnabledLayerNames, and enabledExtensionCount and ppEnabledExtensionNames. The VkApplicationInfo structure provides optional metadata such as application name, engine name, application version, engine version, and the Vulkan API version the application targets.

Behavior and usage: vkCreateInstance interacts with the system loader and the Vulkan driver. If requested layers or extensions are not present, the function may fail with VK_ERROR_LAYER_NOT_PRESENT or VK_ERROR_EXTENSION_NOT_PRESENT. If insufficient memory is available, it may return VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY. Other possible errors include VK_ERROR_INITIALIZATION_FAILED and VK_ERROR_INCOMPATIBLE_DRIVER. On success, the caller receives a valid VkInstance handle and should eventually destroy it with vkDestroyInstance.

Related functions include vkDestroyInstance, vkEnumerateInstanceExtensions, and vkEnumerateInstanceLayerProperties.