1# vulkan_ohos.h 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphic--> 5<!--Owner: @andrew1993--> 6<!--Designer: @ext4FAT1--> 7<!--Tester: @nobuggers--> 8<!--Adviser: @ge-yafang--> 9 10## 概述 11 12定义了OpenHarmony平台扩展的Vulkan接口。 13 14**引用文件：** <vulkan/vulkan_ohos.h> 15 16**库：** libvulkan.so 17 18**起始版本：** 10 19 20**相关模块：** [Vulkan](capi-vulkan.md) 21 22## 汇总 23 24### 结构体 25 26| 名称 | typedef关键字 | 描述 | 27|-----------------------------------------------------------------------------------------|------------------------------------|----------------------------------| 28| [VkSurfaceCreateInfoOHOS](capi-vulkan-vksurfacecreateinfoohos.md) | VkSurfaceCreateInfoOHOS | 包含创建Vulkan Surface时必要的参数。 | 29| [VkNativeBufferUsageOHOS](capi-vulkan-vknativebufferusageohos.md) | VkNativeBufferUsageOHOS | 提供OpenHarmony NativeBuffer用途的说明。 | 30| [VkNativeBufferPropertiesOHOS](capi-vulkan-vknativebufferpropertiesohos.md) | VkNativeBufferPropertiesOHOS | 包含了NativeBuffer的属性。 | 31| [VkNativeBufferFormatPropertiesOHOS](capi-vulkan-vknativebufferformatpropertiesohos.md) | VkNativeBufferFormatPropertiesOHOS | 包含了NativeBuffer的一些格式属性。 | 32| [VkImportNativeBufferInfoOHOS](capi-vulkan-vkimportnativebufferinfoohos.md) | VkImportNativeBufferInfoOHOS | 包含了OH_NativeBuffer结构体的指针。 | 33| [VkMemoryGetNativeBufferInfoOHOS](capi-vulkan-vkmemorygetnativebufferinfoohos.md) | VkMemoryGetNativeBufferInfoOHOS | 用于从Vulkan内存中获取OH_NativeBuffer。 | 34| [VkExternalFormatOHOS](capi-vulkan-vkexternalformatohos.md) | VkExternalFormatOHOS | 表示外部定义的格式标识符。 | 35| [NativeWindow](capi-vulkan-nativewindow.md) | OHNativeWindow | 本地窗口。 | 36| [OH_NativeBuffer](capi-vulkan-oh-nativebuffer.md) | - | OH_NativeBuffer结构体声明。 | 37 38### 宏定义 39 40| 名称 | 描述 | 41| -- | -- | 42| VK_OHOS_surface 1 | OpenHarmony平台Surface扩展宏定义。<br>**起始版本：** 10 | 43| VK_OHOS_SURFACE_SPEC_VERSION 1 | OpenHarmony平台Surface扩展版本号。<br>**起始版本：** 10 | 44| VK_OHOS_SURFACE_EXTENSION_NAME "VK_OHOS_surface" | OpenHarmony平台Surface扩展名。<br>**起始版本：** 10 | 45| VK_OHOS_external_memory 1 | OpenHarmony平台external_memory扩展宏定义。<br>**起始版本：** 10 | 46| VK_OHOS_EXTERNAL_MEMORY_SPEC_VERSION 1 | OpenHarmony平台external_memory扩展版本号。<br>**起始版本：** 10 | 47| VK_OHOS_EXTERNAL_MEMORY_EXTENSION_NAME "VK_OHOS_external_memory" | OpenHarmony平台external_memory扩展名。<br>**起始版本：** 10 | 48 49### 函数 50 51| 名称 | typedef关键字 | 描述 | 52|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|-----------------------------| 53| [VkResult (VKAPI_PTR *PFN_vkCreateSurfaceOHOS)(VkInstance instance, const VkSurfaceCreateInfoOHOS* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSurfaceKHR* pSurface)](#pfn_vkcreatesurfaceohos) | PFN_vkCreateSurfaceOHOS | 创建Vulkan Surface的函数指针定义。 | 54| [VKAPI_ATTR VkResult VKAPI_CALL vkCreateSurfaceOHOS(VkInstance instance, const VkSurfaceCreateInfoOHOS* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSurfaceKHR* pSurface)](#vkcreatesurfaceohos) | - | 创建Vulkan Surface。 | 55| [VkResult (VKAPI_PTR *PFN_vkGetNativeBufferPropertiesOHOS)(VkDevice device, const struct OH_NativeBuffer* buffer, VkNativeBufferPropertiesOHOS* pProperties)](#pfn_vkgetnativebufferpropertiesohos) | PFN_vkGetNativeBufferPropertiesOHOS | 获取OH_NativeBuffer属性的函数指针定义。 | 56| [VkResult (VKAPI_PTR *PFN_vkGetMemoryNativeBufferOHOS)(VkDevice device, const VkMemoryGetNativeBufferInfoOHOS* pInfo, struct OH_NativeBuffer** pBuffer)](#pfn_vkgetmemorynativebufferohos) | PFN_vkGetMemoryNativeBufferOHOS | 获取OH_NativeBuffer的函数指针定义。 | 57| [VKAPI_ATTR VkResult VKAPI_CALL vkGetNativeBufferPropertiesOHOS(VkDevice device, const struct OH_NativeBuffer* buffer, VkNativeBufferPropertiesOHOS* pProperties)](#vkgetnativebufferpropertiesohos) | - | 获取OH_NativeBuffer属性。 | 58| [VKAPI_ATTR VkResult VKAPI_CALL vkGetMemoryNativeBufferOHOS(VkDevice device, const VkMemoryGetNativeBufferInfoOHOS* pInfo, struct OH_NativeBuffer** pBuffer)](#vkgetmemorynativebufferohos) | - | 获取OH_NativeBuffer。 | 59| [VKAPI_ATTR VkResult VKAPI_CALL vkGetSwapchainGrallocUsageOHOS(VkDevice device, VkFormat format, VkImageUsageFlags imageUsage, uint64_t* grallocUsage)](#vkgetswapchaingrallocusageohos) | - | 根据给定的Vulkan设备、图像格式和图像使用标志, 返回适当的Gralloc(内存分配器)使用标志。 | 60| [VKAPI_ATTR VkResult VKAPI_CALL vkAcquireImageOHOS(VkDevice device, VkImage image, int32_t nativeFenceFd, VkSemaphore semaphore, VkFence fence)](#vkacquireimageohos) | - | 用于获取交换链图像的所有权, 并将外部信号的Fence导入到VkSemaphore对象和VkFence对象中。 | 61| [VKAPI_ATTR VkResult VKAPI_CALL vkQueueSignalReleaseImageOHOS(VkQueue queue, uint32_t waitSemaphoreCount, const VkSemaphore* pWaitSemaphores, VkImage image, int32_t* pNativeFenceFd)](#vkqueuesignalreleaseimageohos) | - | 当前图像使用完毕后，通过该函数向系统硬件缓冲区发出释放信号, 以便其他组件可以访问该图像。 | 62 63## 函数说明 64 65### PFN_vkCreateSurfaceOHOS() 66 67``` 68typedef VkResult (VKAPI_PTR *PFN_vkCreateSurfaceOHOS)(VkInstance instance, const VkSurfaceCreateInfoOHOS* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSurfaceKHR* pSurface) 69``` 70 71**描述** 72 73创建Vulkan Surface的函数指针定义。 74 75**系统能力：** SystemCapability.Graphic.Vulkan 76 77**起始版本：** 10 78 79 80**参数：** 81 82| 参数项 | 描述 | 83| -- | -- | 84| VkInstance instance | Vulkan实例。 | 85| [const VkSurfaceCreateInfoOHOS](capi-vulkan-vksurfacecreateinfoohos.md)* pCreateInfo | 一个VkSurfaceCreateInfoOHOS结构体的指针，包含创建Vulkan Surface时必要的参数。 | 86| const VkAllocationCallbacks* pAllocator | 用户自定义内存分配的回调函数，如果不需要可以传入NULL，接口会使用默认的内存分配函数。 | 87| VkSurfaceKHR* pSurface | 出参，用于接收创建的Vulkan Surface，类型为VkSurfaceKHR。 | 88 89**返回：** 90 91| 类型 | 说明 | 92| -- | -- | 93| VkResult | 返回一个VkResult类型的错误码，返回值为VK_SUCCESS表示执行成功。 | 94 95### vkCreateSurfaceOHOS() 96 97``` 98VKAPI_ATTR VkResult VKAPI_CALL vkCreateSurfaceOHOS(VkInstance instance, const VkSurfaceCreateInfoOHOS* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSurfaceKHR* pSurface) 99``` 100 101**描述** 102 103创建Vulkan Surface。 104 105**系统能力：** SystemCapability.Graphic.Vulkan 106 107**起始版本：** 10 108 109 110**参数：** 111 112| 参数项 | 描述 | 113| -- | -- | 114| VkInstance instance | Vulkan实例。 | 115| [const VkSurfaceCreateInfoOHOS](capi-vulkan-vksurfacecreateinfoohos.md)* pCreateInfo | 一个VkSurfaceCreateInfoOHOS结构体的指针，包含创建Vulkan Surface时必要的参数。 | 116| const VkAllocationCallbacks* pAllocator | 用户自定义内存分配的回调函数，如果不需要可以传入NULL，接口会使用默认的内存分配函数。 | 117| VkSurfaceKHR* pSurface | 出参，用于接收创建的Vulkan Surface，类型为VkSurfaceKHR。 | 118 119**返回：** 120 121| 类型 | 说明 | 122| -- | -- | 123| VkResult | 返回一个VkResult类型的错误码，具体返回类型如下：<br> 返回VK_SUCCESS，表示执行成功。<br> 返回VK_ERROR_OUT_OF_HOST_MEMORY，表示分配VkSurfaceKHR内存失败。<br> 返回VK_ERROR_SURFACE_LOST_KHR，表示操作NativeWindow失败。 | 124 125### PFN_vkGetNativeBufferPropertiesOHOS() 126 127``` 128typedef VkResult (VKAPI_PTR *PFN_vkGetNativeBufferPropertiesOHOS)(VkDevice device, const struct OH_NativeBuffer* buffer, VkNativeBufferPropertiesOHOS* pProperties) 129``` 130 131**描述** 132 133获取OH_NativeBuffer属性的函数指针定义。 134 135**系统能力：** SystemCapability.Graphic.Vulkan 136 137**起始版本：** 10 138 139 140**参数：** 141 142| 参数项 | 描述 | 143|------------------------------------------------------------------------| -- | 144| VkDevice device | VkDevice对象。 | 145| const [struct OH_NativeBuffer](capi-vulkan-oh-nativebuffer.md)* buffer | OH_NativeBuffer结构体指针。 | 146| [VkNativeBufferPropertiesOHOS](capi-vulkan-vknativebufferpropertiesohos.md)* pProperties | 用于接收OH_NativeBuffer属性的结构体。 | 147 148**返回：** 149 150| 类型 | 说明 | 151| -- | -- | 152| VkResult | 返回一个VkResult类型的错误码，返回值为VK_SUCCESS表示执行成功。 | 153 154### PFN_vkGetMemoryNativeBufferOHOS() 155 156``` 157typedef VkResult (VKAPI_PTR *PFN_vkGetMemoryNativeBufferOHOS)(VkDevice device, const VkMemoryGetNativeBufferInfoOHOS* pInfo, struct OH_NativeBuffer** pBuffer) 158``` 159 160**描述** 161 162获取OH_NativeBuffer的函数指针定义。 163 164**系统能力：** SystemCapability.Graphic.Vulkan 165 166**起始版本：** 10 167 168 169**参数：** 170 171| 参数项 | 描述 | 172| -- | -- | 173| VkDevice device | VkDevice对象。 | 174| [const VkMemoryGetNativeBufferInfoOHOS](capi-vulkan-vkmemorygetnativebufferinfoohos.md)* pInfo | VkMemoryGetNativeBufferInfoOHOS结构体对象。 | 175| [struct OH_NativeBuffer](capi-vulkan-oh-nativebuffer.md)** pBuffer | 用于接收获取到的OH_NativeBuffer。 | 176 177**返回：** 178 179| 类型 | 说明 | 180| -- | -- | 181| VkResult | 返回一个VkResult类型的错误码，返回值为VK_SUCCESS表示执行成功。 | 182 183### vkGetNativeBufferPropertiesOHOS() 184 185``` 186VKAPI_ATTR VkResult VKAPI_CALL vkGetNativeBufferPropertiesOHOS(VkDevice device, const struct OH_NativeBuffer* buffer, VkNativeBufferPropertiesOHOS* pProperties) 187``` 188 189**描述** 190 191获取OH_NativeBuffer属性。 192 193**系统能力：** SystemCapability.Graphic.Vulkan 194 195**起始版本：** 10 196 197 198**参数：** 199 200| 参数项 | 描述 | 201| -- | -- | 202| VkDevice device | VkDevice对象。 | 203| const [struct OH_NativeBuffer](capi-vulkan-oh-nativebuffer.md)* buffer | OH_NativeBuffer结构体指针。 | 204| [VkNativeBufferPropertiesOHOS](capi-vulkan-vknativebufferpropertiesohos.md)* pProperties | 用于接收OH_NativeBuffer属性的结构体。 | 205 206**返回：** 207 208| 类型 | 说明 | 209| -- | -- | 210| VkResult | 返回一个VkResult类型的错误码，具体返回类型如下：<br> 返回VK_SUCCESS，表示执行成功。<br> 返回VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR，表示入参存在异常。<br> 返回VK_ERROR_OUT_OF_DEVICE_MEMORY，表示设备内存不足。 | 211 212### vkGetMemoryNativeBufferOHOS() 213 214``` 215VKAPI_ATTR VkResult VKAPI_CALL vkGetMemoryNativeBufferOHOS(VkDevice device, const VkMemoryGetNativeBufferInfoOHOS* pInfo, struct OH_NativeBuffer** pBuffer) 216``` 217 218**描述** 219 220获取OH_NativeBuffer。 221 222**系统能力：** SystemCapability.Graphic.Vulkan 223 224**起始版本：** 10 225 226 227**参数：** 228 229| 参数项 | 描述 | 230| -- | -- | 231| VkDevice device | VkDevice对象。 | 232| [const VkMemoryGetNativeBufferInfoOHOS](capi-vulkan-vkmemorygetnativebufferinfoohos.md)* pInfo | VkMemoryGetNativeBufferInfoOHOS结构体对象。 | 233| [struct OH_NativeBuffer](capi-vulkan-oh-nativebuffer.md)** pBuffer | 用于接收获取到的OH_NativeBuffer。 | 234 235**返回：** 236 237| 类型 | 说明 | 238| -- | -- | 239| VkResult | 返回一个VkResult类型的错误码，具体返回类型如下：<br> 返回VK_SUCCESS，表示执行成功。<br> 返回VK_ERROR_OUT_OF_HOST_MEMORY，表示pInfo入参异常，或获取的pBuffer异常。 | 240 241### vkGetSwapchainGrallocUsageOHOS() 242 243``` 244VKAPI_ATTR VkResult VKAPI_CALL vkGetSwapchainGrallocUsageOHOS(VkDevice device, VkFormat format, VkImageUsageFlags imageUsage, uint64_t* grallocUsage) 245``` 246 247**描述** 248 249根据给定的Vulkan设备、图像格式和图像使用标志, 返回适当的Gralloc(内存分配器)使用标志。 250 251**系统能力：** SystemCapability.Graphic.Vulkan 252 253**起始版本：** 10 254 255 256**参数：** 257 258| 参数项 | 描述 | 259| -- | -- | 260| VkDevice device | VkDevice对象。 | 261| VkFormat format | 图像格式。 | 262| VkImageUsageFlags imageUsage | 图像使用标志。 | 263| uint64_t* grallocUsage | 出参, 返回Gralloc(内存分配器)使用标志。 | 264 265**返回：** 266 267| 类型 | 说明 | 268| -- | -- | 269| VkResult | 返回一个VkResult类型的错误码，具体返回类型如下：<br> 返回VK_SUCCESS，表示执行成功。<br> 返回VK_ERROR_INITIALIZATION_FAILED，表示入参异常。 | 270 271### vkAcquireImageOHOS() 272 273``` 274VKAPI_ATTR VkResult VKAPI_CALL vkAcquireImageOHOS(VkDevice device, VkImage image, int32_t nativeFenceFd, VkSemaphore semaphore, VkFence fence) 275``` 276 277**描述** 278 279用于获取交换链图像的所有权, 并将外部信号的Fence导入到VkSemaphore对象和VkFence对象中。 280 281**系统能力：** SystemCapability.Graphic.Vulkan 282 283**起始版本：** 10 284 285 286**参数：** 287 288| 参数项 | 描述 | 289| -- | -- | 290| VkDevice device | VkDevice对象。 | 291| VkImage image | 要获取的Vulkan图像。 | 292| int32_t nativeFenceFd | 原生Fence的文件描述符。 | 293| VkSemaphore semaphore | 表示图像可用状态的Vulkan Semaphore(信号量)。 | 294| VkFence fence | 用于在图像获取完成时进行同步的Vulkan Fence。 | 295 296**返回：** 297 298| 类型 | 说明 | 299| -- | -- | 300| VkResult | 返回一个VkResult类型的错误码，具体返回类型如下：<br> 返回VK_SUCCESS，表示执行成功。<br> 返回VK_ERROR_OUT_OF_HOST_MEMORY，表示主机内存不足。 | 301 302### vkQueueSignalReleaseImageOHOS() 303 304``` 305VKAPI_ATTR VkResult VKAPI_CALL vkQueueSignalReleaseImageOHOS(VkQueue queue, uint32_t waitSemaphoreCount, const VkSemaphore* pWaitSemaphores, VkImage image, int32_t* pNativeFenceFd) 306``` 307 308**描述** 309 310当前图像使用完毕后，通过该函数向系统硬件缓冲区发出释放信号, 以便其他组件可以访问该图像。 311 312**系统能力：** SystemCapability.Graphic.Vulkan 313 314**起始版本：** 10 315 316 317**参数：** 318 319| 参数项 | 描述 | 320| -- | -- | 321| VkQueue queue | Vulkan队列的句柄。 | 322| uint32_t waitSemaphoreCount | 等待Semaphore(信号量)的数量。 | 323| const VkSemaphore* pWaitSemaphores | 指向等待Semaphore(信号量)数组的指针。 | 324| VkImage image | 要释放的Vulkan图像句柄。 | 325| int32_t* pNativeFenceFd | 指向Fence的文件描述符的指针。 | 326 327**返回：** 328 329| 类型 | 说明 | 330| -- | -- | 331| VkResult | 返回一个VkResult类型的错误码，具体返回类型如下：<br> 返回VK_SUCCESS，表示执行成功。<br> 返回VK_ERROR_DEVICE_LOST，表示Vulkan设备链接丢失。<br> 返回VK_ERROR_OUT_OF_HOST_MEMORY，表示主机内存不足。 | 332 333 334