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.