Vulkan规范：第三章

3. 初始化

在使用Vulkan之前，应用程序必须通过载入Vulkan命令和创建VkInstance对象来初始化它。

3.1. 命令函数的指针

Vulkan命令在各平台上并不是静态的暴露出来的。可以通过以下命令来获取Vulkan命令的函数指针：

PFN_vkVoidFunction vkGetInstanceProcAddr(    VkInstance                                  instance,    const char*                                 pName);

• instance is the instance that the function pointer will be compatible with, or NULL for commands not dependent on any instance.

• pName 是需要获取的命令的名字。

vkGetInstanceProcAddr 自己是通过平台和loader各异的方式获取的。通常，loader库将以函数符号的方式导出这个命令， 所以，应用程序可以链接到loader库，或者动态的载入并使用平台自己的API来寻找符号。 loader应导出其他所有的核心Vulkan命令；如果完成了，应用程序只使用核心的Vulkan命令，就没有必要使用vkGetInstanceProcAddr了。

下面的表格定义了vkGetInstanceProcAddr 各种使用场景和期待的返回值（fp 是函数指针）：

返回的函数指针是 PFN_vkVoidFunction 类型的，必须强制转换为查询所用的类型：

Table 1. vkGetInstanceProcAddr behaviorinstancepNamereturn value

*

NULL

undefined

invalid instance

*

undefined

NULL

vkEnumerateInstanceExtensionProperties

fp

NULL

vkEnumerateInstanceLayerProperties

fp

NULL

vkCreateInstance

fp

NULL

* (any pName not covered above)

NULL

instance

core Vulkan command

fp1

instance

enabled instance extension commands for instance

fp1

instance

available device extension2 commands for instance

fp1

instance

* (any pName not covered above)

NULL

1

The returned function pointer must only be called with a dispatchable object (the first parameter) that is instance or a child of instance. e.g. VkInstance, VkPhysicalDevice, VkDevice, VkQueue, or VkCommandBuffer.

2

An “available extension” is an extension function supported by any of the loader, driver or layer.

Valid Usage (Implicit)

• If instance is not NULL, instance must be a valid VkInstance handle

• pName must be a null-terminated string

为了支持有多个Vulkan实现的异构系统，vkGetInstanceProcAddr 返回的函数指针可能指向 不可可分发的代码，亦即 对不同的VkDevice对象调用不同的真实实现。 这个内部分发的开销可以通过获取设备各异的函数指针而避免，这些命令使用设备或者设备子对象作为不可分发对象。 这些函数指针可通过以下命令获取：

PFN_vkVoidFunction vkGetDeviceProcAddr(    VkDevice                                    device,    const char*                                 pName);

下面的表格定义了使用vkGetDeviceProcAddr的各种场景和各自期待的返回值。

返回的函数指针是 PFN_vkVoidFunction 类型的，必须强制转换为查询所用的类型：

Table 2. vkGetDeviceProcAddr behaviordevicepNamereturn value

NULL

*

undefined

invalid device

*

undefined

device

NULL

undefined

device

core Vulkan command

fp1

device

enabled extension commands

fp1

device

* (any pName not covered above)

NULL

1

The returned function pointer must only be called with a dispatchable object (the first parameter) that is device or a child of device. e.g. VkDevice, VkQueue, or VkCommandBuffer.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pName must be a null-terminated string

The definition of PFN_vkVoidFunction is:

typedef void (VKAPI_PTR *PFN_vkVoidFunction)(void);

3.2. 实例

在Vulkan中没有全局的状态，所有应用程序自己的状态都存储在一个VkInstance对象中。 创建一个VkInstance 对象会初始化Vulkan库并允许应用程序传递信息给Vulkan实现。

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创建一个实例，然后启用并初始化应用程序需要的全局层和拓展。 如果一个拓展通过一个层提供，那么层和拓展都必须在vkCreateInstance指定。 如果指定的层没有被找到，那么将不会创建VkInstance对象，函数将返回VK_ERROR_LAYER_NOT_PRESENT。 同样，如果一个指定的拓展没有被找到，函数调用将返回VK_ERROR_EXTENSION_NOT_PRESENT。

Valid Usage (Implicit)

• 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

Success

• VK_SUCCESS

Failure

• 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

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.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO

• pNext must be NULL

• flags must be 0

• If pApplicationInfo is not NULL, pApplicationInfo must be a pointer to a valid VkApplicationInfo structure

• If enabledLayerCount is not 0, ppEnabledLayerNames must be a pointer to an array of enabledLayerCount null-terminated strings

• If enabledExtensionCount is not 0, ppEnabledExtensionNames must be a pointer to an array of enabledExtensionCount null-terminated strings

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 theAPI 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.

Valid Usage

• apiVersion must be zero, or otherwise it must be a version that the implementation supports, or supports an effective substitute for

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_APPLICATION_INFO

• pNext must be NULL

• If pApplicationName is not NULL, pApplicationName must be a null-terminated string

• If pEngineName is not NULL, pEngineName must be a null-terminated string

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.

Valid Usage

• All child objects created using instance must have been destroyed prior to destroying instance

• If VkAllocationCallbacks were provided when instance was created, a compatible set of callbacks must be provided here

• If no VkAllocationCallbacks were provided when instance was created, pAllocator must be NULL

Valid Usage (Implicit)

• If instance is not NULL, instance must be a valid VkInstance handle

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

Host Synchronization

• Host access to instance must be externally synchronized