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:
VK_DEFINE_HANDLE(VkInstance)
To create an instance object, call:
VkResult vkCreateInstance(
const VkInstanceCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkInstance* pInstance);
pCreateInfo points to an instance of VkInstanceCreateInfo
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 creates the instance, then enables and initializes
global layers and extensions requested by the application.
If an extension is provided by a layer, both the layer and extension must
be specified at vkCreateInstance time.
If a specified layer cannot be found, no VkInstance will be created
and the function will return VK_ERROR_LAYER_NOT_PRESENT.
Likewise, if a specified extension cannot be found the call will return
VK_ERROR_EXTENSION_NOT_PRESENT.
The VkInstanceCreateInfo structure is defined as:
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 the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
flags is reserved for future use.
pApplicationInfo is NULL or a pointer to an instance of
VkApplicationInfo.
If not NULL, 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 of
enabledLayerCount null-terminated UTF-8 strings containing the
names of layers to enable for the created instance.
See the Layers section for further
details.
enabledExtensionCount is the number of global extensions to
enable.
ppEnabledExtensionNames is a pointer to an array of
enabledExtensionCount null-terminated UTF-8 strings containing the
names of extensions to enable.
The VkApplicationInfo structure is defined as:
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 the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
pApplicationName 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 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 is the version of the Vulkan API against which the
application expects to run, encoded as described in the
API Version Numbers and Semantics section.
If apiVersion is 0 the implementation must ignore it, otherwise
if the implementation does not support the requested apiVersion it
must return VK_ERROR_INCOMPATIBLE_DRIVER.
The patch version number specified in apiVersion is ignored when
creating an instance object.
Only the major and minor versions of the instance must match those
requested in apiVersion.
To destroy an instance, call:
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.