VKCREATEINSTANCE(3)

NAME
vkCreateInstance - Create a new Vulkan instance

C SPECIFICATION

    VkResult vkCreateInstance(
        const VkInstanceCreateInfo*                 pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkInstance*                                 pInstance);

PARAMETERS

pCreateInfo
    Pointer to instance creation structure.

pInstance
    Pointer to variable which will receive the new instance handle.

DESCRIPTION

vkCreateInstance creates a new Vulkan instance and places a handle to it in the variable pointed to by pInstance. pCreateInfo is a pointer to an instance of the VkInstanceCreateInfo structure containing information about how the instance should be created. The definition of VkInstanceCreateInfo is:

    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;

The sType member of VkInstanceCreateInfo should be set to VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO. The pNext member of VkInstanceCreateInfo is reserved for use by extensions and should be set to NULL.

The pApplicationInfo member, if non-NULL, points to an instance of the VkApplicationInfo structure containing information about the application. The expected contents of the pApplicationInfo member are documented below.

The enabledLayerNameCount member of VkInstanceCreateInfo specifies the number of global layers to enable, and ppEnabledLayerNames is a pointer to an array of enabledLayerNameCount NULL-terminated UTF-8 strings containing the names of layers that should be enabled globally. If enabledLayerNameCount is zero, then ppEnabledLayerNames is ignored and no global layers are enabled.

Similary, information about global extensions is specified in the enabledExtensionNameCount and ppEnabledExtensionNames members. enabledExtensionNameCount specifies the number of global extensions to enable and ppEnabledExtensionNames is a pointer to an array of pointers to NULL-terminated UTF-8 strings containing the extension names. If an extension is provided by a layer, both the layer and extension must be specified at vkCreateInstance time.

If enabledExtensionNameCount is zero then no extensions are enabled and ppEnabledExtensionNames is ignored.

The definition of the VkApplicationInfo structure is as follows:

    typedef struct VkApplicationInfo {
        VkStructureType    sType;
        const void*        pNext;
        const char*        pApplicationName;
        uint32_t           applicationVersion;
        const char*        pEngineName;
        uint32_t           engineVersion;
        uint32_t           apiVersion;
    } VkApplicationInfo;

The sType member of VkApplicationInfo should be set to VK_STRUCTURE_TYPE_APPLICATION_INFO. The pNext member of VkApplicationInfo is reserved for use by extensions and should be set to NULL.

pApplicationName is a pointer to a NULL-terminated UTF-8 string containing the name of the application. applicationVersion contains an application-specific version number. It is recommended that new versions of an existing application specify monotonically increasing values for applicationVersion.

If the application is built on a reusable engine, the name of the engine may be specified in the NULL-terminated UTF-8 string pointed to by pEngineName. engineVersion is the version of the engine used to create the application.

Finally, apiVersion is the version of the Vulkan API that the application expects to use.

Any application memory required by the instance will be allocated by calling functions specified in the structure pointed to by pAllocCb. The definition of VkAllocationCallbacks is:

    typedef struct VkAllocationCallbacks {
        void*                                   pUserData;
        PFN_vkAllocationFunction                pfnAllocation;
        PFN_vkReallocationFunction              pfnReallocation;
        PFN_vkFreeFunction                      pfnFree;
        PFN_vkInternalAllocationNotification    pfnInternalAllocation;
        PFN_vkInternalFreeNotification          pfnInternalFree;
    } VkAllocationCallbacks;

The VkAllocationCallbacks structure contains two function pointers. pfnAllocation points to an allocation function whose protoype should be of the following form:

    typedef void* (*PFN_vkAllocationFunction)(
        void*                                       pUserData,
        size_t                                      size,
        size_t                                      alignment,
        VkSystemAllocationScope                     allocationScope);

pUserData is set to the value of pUserData in the allocation info structure passed to vkCreateInstance. size is the size of the desired allocation, alignment is the desired allocation, in bytes, and allocationScope represents the intended usage of the allocation. The return value of function is a pointer to the newly allocated memory.

The pfnFree member of VkAllocationCallbacks points to an instance of the following function:

    typedef void (*PFN_vkFreeFunction)(
        void*                                       pUserData,
        void*                                       pMemory);

Again, the pUserData parameter is initialized to the value passed in the VkAllocationCallbacks structure passed to vkCreateInstance. pMemory is a pointer to the memory to be freed.

VALID USAGE

    • pCreateInfo must be a pointer to a valid VkInstanceCreateInfo structure

    • If pAllocator is not NULL, pAllocator must be a pointer to a valid VkAllocationCallbacks structure

    • pInstance must be a pointer to a VkInstance handle

RETURN CODES

On success, this command returns

        • VK_SUCCESS

On failure, this command returns

        • VK_ERROR_OUT_OF_HOST_MEMORY

        • VK_ERROR_OUT_OF_DEVICE_MEMORY

        • VK_ERROR_INITIALIZATION_FAILED

        • VK_ERROR_LAYER_NOT_PRESENT

        • VK_ERROR_EXTENSION_NOT_PRESENT

        • VK_ERROR_INCOMPATIBLE_DRIVER

SEE ALSO

vkDestroyInstance

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.