目录

Vulkan模块

概述

提供HarmonyOS平台扩展的Vulkan能力，扩展了使用OHNativeWindow创建Vulkan Surface的能力，以及获取OH_NativeBuffer和OH_NativeBuffer属性的能力。

@syscap SystemCapability.Graphic.Vulkan

起始版本：

10

汇总

[h2]文件

名称 描述
vulkan_ohos.h

定义了HarmonyOS平台扩展的Vulkan接口。

引用文件：<vulkan/vulkan.h>

库：libvulkan.so

[h2]结构体

名称 描述
VkSurfaceCreateInfoOHOS 包含创建Vulkan Surface时必要的参数。
VkNativeBufferUsageOHOS 提供HarmonyOS NativeBuffer用途的说明。
VkNativeBufferPropertiesOHOS 包含了NativeBuffer的属性。
VkNativeBufferFormatPropertiesOHOS 包含了NativeBuffer的一些格式属性。
VkImportNativeBufferInfoOHOS 包含了OH_NativeBuffer结构体的指针。
VkMemoryGetNativeBufferInfoOHOS 用于从Vulkan内存中获取OH_NativeBuffer。
VkExternalFormatOHOS 表示外部定义的格式标识符。

[h2]宏定义

名称 描述
VK_OHOS_surface 1 HarmonyOS平台Surface扩展宏定义。
VK_OHOS_SURFACE_SPEC_VERSION 1 HarmonyOS平台Surface扩展版本号。
VK_OHOS_SURFACE_EXTENSION_NAME "VK_OHOS_surface" HarmonyOS平台Surface扩展名。
VK_OHOS_external_memory 1 HarmonyOS平台external_memory扩展宏定义。
VK_OHOS_EXTERNAL_MEMORY_SPEC_VERSION 1 HarmonyOS平台external_memory扩展版本号。
VK_OHOS_EXTERNAL_MEMORY_EXTENSION_NAME "VK_OHOS_external_memory" HarmonyOS平台external_memory扩展名。

[h2]类型定义

名称 描述
OHNativeWindow OH本地窗口。
VkSurfaceCreateFlagsOHOS 用于Vulkan Surface创建时使用到的VkFlags类型位掩码，预留的标志类型。
VkSurfaceCreateInfoOHOS 包含创建Vulkan Surface时必要的参数。
VkResult (VKAPI_PTR *PFN_vkCreateSurfaceOHOS) (VkInstance instance, const VkSurfaceCreateInfoOHOS *pCreateInfo, const VkAllocationCallbacks *pAllocator, VkSurfaceKHR *pSurface) 创建Vulkan Surface的函数指针定义。
VkNativeBufferUsageOHOS 提供HarmonyOS NativeBuffer用途的说明。
VkNativeBufferPropertiesOHOS 包含了NativeBuffer的属性。
VkNativeBufferFormatPropertiesOHOS 包含了NativeBuffer的一些格式属性。
VkImportNativeBufferInfoOHOS 包含了OH_NativeBuffer结构体的指针。
VkMemoryGetNativeBufferInfoOHOS 用于从Vulkan内存中获取OH_NativeBuffer。
VkExternalFormatOHOS 表示外部定义的格式标识符。
VkResult (VKAPI_PTR *PFN_vkGetNativeBufferPropertiesOHOS) (VkDevice device, const struct OH_NativeBuffer *buffer, VkNativeBufferPropertiesOHOS *pProperties) 获取OH_NativeBuffer属性的函数指针定义。
VkResult (VKAPI_PTR *PFN_vkGetMemoryNativeBufferOHOS) (VkDevice device, const VkMemoryGetNativeBufferInfoOHOS *pInfo, struct OH_NativeBuffer **pBuffer) 获取OH_NativeBuffer的函数指针定义。

[h2]函数

名称 描述
VKAPI_ATTR VkResult VKAPI_CALL vkCreateSurfaceOHOS (VkInstance instance, const VkSurfaceCreateInfoOHOS *pCreateInfo, const VkAllocationCallbacks *pAllocator, VkSurfaceKHR *pSurface) 创建Vulkan Surface。
VKAPI_ATTR VkResult VKAPI_CALL vkGetNativeBufferPropertiesOHOS (VkDevice device, const struct OH_NativeBuffer *buffer, VkNativeBufferPropertiesOHOS *pProperties) 获取OH_NativeBuffer属性。
VKAPI_ATTR VkResult VKAPI_CALL vkGetMemoryNativeBufferOHOS (VkDevice device, const VkMemoryGetNativeBufferInfoOHOS *pInfo, struct OH_NativeBuffer **pBuffer) 获取OH_NativeBuffer。
VKAPI_ATTR VkResult VKAPI_CALL vkGetSwapchainGrallocUsageOHOS (VkDevice device, VkFormat format, VkImageUsageFlags imageUsage, uint64_t *grallocUsage) 根据给定的Vulkan设备、图像格式和图像使用标志, 返回适当的Gralloc(内存分配器)使用标志。
VKAPI_ATTR VkResult VKAPI_CALL vkAcquireImageOHOS (VkDevice device, VkImage image, int32_t nativeFenceFd, VkSemaphore semaphore, VkFence fence) 用于获取交换链图像的所有权, 并将外部信号的Fence导入到VkSemaphore对象和VkFence对象中。
VKAPI_ATTR VkResult VKAPI_CALL vkQueueSignalReleaseImageOHOS (VkQueue queue, uint32_t waitSemaphoreCount, const VkSemaphore *pWaitSemaphores, VkImage image, int32_t *pNativeFenceFd) 当前图像使用完毕后，通过该函数向系统硬件缓冲区发出释放信号, 以便其他组件可以访问该图像。

[h2]变量

名称 描述
VkSurfaceCreateInfoOHOS::sType 结构体类型。
VkSurfaceCreateInfoOHOS::pNext 下一级结构体指针。
VkSurfaceCreateInfoOHOS::flags 预留的标志类型参数。
VkSurfaceCreateInfoOHOS::window OHNativeWindow指针。
VkNativeBufferUsageOHOS::sType 结构体类型。
VkNativeBufferUsageOHOS::pNext 下一级结构体指针。
VkNativeBufferUsageOHOS::OHOSNativeBufferUsage NativeBuffer的用途说明。
VkNativeBufferPropertiesOHOS::sType 结构体类型。
VkNativeBufferPropertiesOHOS::pNext 下一级结构体指针。
VkNativeBufferPropertiesOHOS::allocationSize 占用的内存大小。
VkNativeBufferPropertiesOHOS::memoryTypeBits 内存类型。
VkNativeBufferFormatPropertiesOHOS::sType 结构体类型。
VkNativeBufferFormatPropertiesOHOS::pNext 下一级结构体指针。
VkNativeBufferFormatPropertiesOHOS::format 格式说明。
VkNativeBufferFormatPropertiesOHOS::externalFormat 外部定义的格式标识符。
VkNativeBufferFormatPropertiesOHOS::formatFeatures 描述了与externalFormat对应的能力。
VkNativeBufferFormatPropertiesOHOS::samplerYcbcrConversionComponents 表示一组VkComponentSwizzle。
VkNativeBufferFormatPropertiesOHOS::suggestedYcbcrModel 色彩模型。
VkNativeBufferFormatPropertiesOHOS::suggestedYcbcrRange 色彩数值范围。
VkNativeBufferFormatPropertiesOHOS::suggestedXChromaOffset X色度偏移。
VkNativeBufferFormatPropertiesOHOS::suggestedYChromaOffset Y色度偏移。
VkImportNativeBufferInfoOHOS::sType 结构体类型。
VkImportNativeBufferInfoOHOS::pNext 下一级结构体指针。
VkImportNativeBufferInfoOHOS::buffer OH_NativeBuffer结构体的指针。
VkMemoryGetNativeBufferInfoOHOS::sType 结构体类型。
VkMemoryGetNativeBufferInfoOHOS::pNext 下一级结构体指针。
VkMemoryGetNativeBufferInfoOHOS::memory VkDeviceMemory对象。
VkExternalFormatOHOS::sType 结构体类型。
VkExternalFormatOHOS::pNext 下一级结构体指针。
VkExternalFormatOHOS::externalFormat 外部定义的格式标识符。

宏定义说明

[h2]VK_OHOS_external_memory

#define VK_OHOS_external_memory   1

描述:

HarmonyOS平台external_memory扩展宏定义。

[h2]VK_OHOS_EXTERNAL_MEMORY_EXTENSION_NAME

#define VK_OHOS_EXTERNAL_MEMORY_EXTENSION_NAME   "VK_OHOS_external_memory"

描述:

HarmonyOS平台external_memory扩展名。

[h2]VK_OHOS_EXTERNAL_MEMORY_SPEC_VERSION

#define VK_OHOS_EXTERNAL_MEMORY_SPEC_VERSION   1

描述:

HarmonyOS平台external_memory扩展版本号。

[h2]VK_OHOS_surface

#define VK_OHOS_surface   1

描述:

HarmonyOS平台Surface扩展宏定义。

[h2]VK_OHOS_SURFACE_EXTENSION_NAME

#define VK_OHOS_SURFACE_EXTENSION_NAME   "VK_OHOS_surface"

描述:

HarmonyOS平台Surface扩展名。

[h2]VK_OHOS_SURFACE_SPEC_VERSION

#define VK_OHOS_SURFACE_SPEC_VERSION   1

描述:

HarmonyOS平台Surface扩展版本号。

类型定义说明

[h2]OHNativeWindow

typedef struct NativeWindow OHNativeWindow

描述:

OH本地窗口。

[h2]PFN_vkCreateSurfaceOHOS

typedef VkResult(VKAPI_PTR * PFN_vkCreateSurfaceOHOS) (VkInstance instance, const VkSurfaceCreateInfoOHOS *pCreateInfo, const VkAllocationCallbacks *pAllocator, VkSurfaceKHR *pSurface)

描述:

创建Vulkan Surface的函数指针定义。

@syscap SystemCapability.Graphic.Vulkan

参数:

名称 描述
instance Vulkan实例。
pCreateInfo 一个VkSurfaceCreateInfoOHOS结构体的指针，包含创建Vulkan Surface时必要的参数。
pAllocator 用户自定义内存分配的回调函数，如果不需要可以传入NULL，接口会使用默认的内存分配函数。
pSurface 出参，用于接收创建的Vulkan Surface，类型为VkSurfaceKHR。

返回:

返回一个VkResult类型的错误码，返回值为VK_SUCCESS表示执行成功。

[h2]PFN_vkGetMemoryNativeBufferOHOS

typedef VkResult(VKAPI_PTR * PFN_vkGetMemoryNativeBufferOHOS) (VkDevice device, const VkMemoryGetNativeBufferInfoOHOS *pInfo, struct OH_NativeBuffer **pBuffer)

描述:

获取OH_NativeBuffer的函数指针定义。

@syscap SystemCapability.Graphic.Vulkan

参数:

名称 描述
device VkDevice对象。
pInfo VkMemoryGetNativeBufferInfoOHOS结构体对象。
pBuffer 用于接收获取到的OH_NativeBuffer。

返回:

返回一个VkResult类型的错误码，返回值为VK_SUCCESS表示执行成功。

[h2]PFN_vkGetNativeBufferPropertiesOHOS

typedef VkResult(VKAPI_PTR * PFN_vkGetNativeBufferPropertiesOHOS) (VkDevice device, const struct OH_NativeBuffer *buffer, VkNativeBufferPropertiesOHOS *pProperties)

描述:

获取OH_NativeBuffer属性的函数指针定义。

@syscap SystemCapability.Graphic.Vulkan

参数:

名称 描述
device VkDevice对象。
buffer OH_NativeBuffer结构体指针。
pProperties 用于接收OH_NativeBuffer属性的结构体。

返回:

返回一个VkResult类型的错误码，返回值为VK_SUCCESS表示执行成功。

[h2]VkExternalFormatOHOS

typedef struct VkExternalFormatOHOS VkExternalFormatOHOS

描述:

表示外部定义的格式标识符。

[h2]VkImportNativeBufferInfoOHOS

typedef struct VkImportNativeBufferInfoOHOS VkImportNativeBufferInfoOHOS

描述:

包含了OH_NativeBuffer结构体的指针。

[h2]VkMemoryGetNativeBufferInfoOHOS

typedef struct VkMemoryGetNativeBufferInfoOHOS VkMemoryGetNativeBufferInfoOHOS

描述:

用于从Vulkan内存中获取OH_NativeBuffer。

[h2]VkNativeBufferFormatPropertiesOHOS

typedef struct VkNativeBufferFormatPropertiesOHOS VkNativeBufferFormatPropertiesOHOS

描述:

包含了NativeBuffer的一些格式属性。

[h2]VkNativeBufferPropertiesOHOS

typedef struct VkNativeBufferPropertiesOHOS VkNativeBufferPropertiesOHOS

描述:

包含了NativeBuffer的属性。

[h2]VkNativeBufferUsageOHOS

typedef struct VkNativeBufferUsageOHOS VkNativeBufferUsageOHOS

描述:

提供HarmonyOS NativeBuffer用途的说明。

[h2]VkSurfaceCreateFlagsOHOS

typedef VkFlags VkSurfaceCreateFlagsOHOS

描述:

用于Vulkan Surface创建时使用到的VkFlags类型位掩码，预留的标志类型。

[h2]VkSurfaceCreateInfoOHOS

typedef struct VkSurfaceCreateInfoOHOS VkSurfaceCreateInfoOHOS

描述:

包含创建Vulkan Surface时必要的参数。

函数说明

[h2]vkAcquireImageOHOS()

VKAPI_ATTR VkResult VKAPI_CALL vkAcquireImageOHOS (VkDevice device, VkImage image, int32_t nativeFenceFd, VkSemaphore semaphore, VkFence fence )

描述

用于获取交换链图像的所有权, 并将外部信号的Fence导入到VkSemaphore对象和VkFence对象中。

系统能力： SystemCapability.Graphic.Vulkan

起始版本： 10

参数:

名称 描述
device VkDevice对象。
image 要获取的Vulkan图像。
nativeFenceFd 原生Fence的文件描述符。
semaphore 表示图像可用状态的Vulkan Semaphore(信号量)。
fence 用于在图像获取完成时进行同步的Vulkan Fence。

返回：

返回一个VkResult类型的错误码，具体返回类型如下：

返回VK_SUCCESS，表示执行成功。

返回VK_ERROR_OUT_OF_HOST_MEMORY，表示主机内存不足。

[h2]vkCreateSurfaceOHOS()

VKAPI_ATTR VkResult VKAPI_CALL vkCreateSurfaceOHOS (VkInstance instance, const VkSurfaceCreateInfoOHOS * pCreateInfo, const VkAllocationCallbacks * pAllocator, VkSurfaceKHR * pSurface )

描述:

创建Vulkan Surface。

@syscap SystemCapability.Graphic.Vulkan

参数:

名称 描述
instance Vulkan实例。
pCreateInfo 一个VkSurfaceCreateInfoOHOS结构体的指针，包含创建Vulkan Surface时必要的参数。
pAllocator 用户自定义内存分配的回调函数，如果不需要可以传入NULL，接口会使用默认的内存分配函数。
pSurface 出参，用于接收创建的Vulkan Surface，类型为VkSurfaceKHR。

返回:

返回一个VkResult类型的错误码，具体返回类型如下：

返回VK_SUCCESS，表示执行成功。

返回VK_ERROR_OUT_OF_HOST_MEMORY，表示分配VkSurfaceKHR内存失败。

返回VK_ERROR_SURFACE_LOST_KHR，表示操作NativeWindow失败。

[h2]vkGetMemoryNativeBufferOHOS()

VKAPI_ATTR VkResult VKAPI_CALL vkGetMemoryNativeBufferOHOS (VkDevice device, const VkMemoryGetNativeBufferInfoOHOS * pInfo, struct OH_NativeBuffer ** pBuffer )

描述:

获取OH_NativeBuffer。

@syscap SystemCapability.Graphic.Vulkan

参数:

名称 描述
device VkDevice对象。
pInfo VkMemoryGetNativeBufferInfoOHOS结构体对象。
pBuffer 用于接收获取到的OH_NativeBuffer。

返回:

返回一个VkResult类型的错误码，具体返回类型如下：

返回VK_SUCCESS，表示执行成功。

返回VK_ERROR_OUT_OF_HOST_MEMORY，表示pInfo入参异常，或获取的pBuffer异常。

[h2]vkGetNativeBufferPropertiesOHOS()

VKAPI_ATTR VkResult VKAPI_CALL vkGetNativeBufferPropertiesOHOS (VkDevice device, const struct OH_NativeBuffer * buffer, VkNativeBufferPropertiesOHOS * pProperties )

描述:

获取OH_NativeBuffer属性。

@syscap SystemCapability.Graphic.Vulkan

参数:

名称 描述
device VkDevice对象。
buffer OH_NativeBuffer结构体指针。
pProperties 用于接收OH_NativeBuffer属性的结构体。

返回:

返回一个VkResult类型的错误码，具体返回类型如下：

返回VK_SUCCESS，表示执行成功。

返回VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR，表示入参存在异常。

返回VK_ERROR_OUT_OF_DEVICE_MEMORY，表示设备内存不足。

[h2]vkGetSwapchainGrallocUsageOHOS()

VKAPI_ATTR VkResult VKAPI_CALL vkGetSwapchainGrallocUsageOHOS (VkDevice device, VkFormat format, VkImageUsageFlags imageUsage, uint64_t* grallocUsage )

描述

根据给定的Vulkan设备、图像格式和图像使用标志, 返回适当的Gralloc(内存分配器)使用标志。

系统能力： SystemCapability.Graphic.Vulkan

起始版本： 10

参数:

名称 描述
device VkDevice对象。
format 图像格式。
imageUsage 图像使用标志。
grallocUsage 出参, 返回Gralloc(内存分配器)使用标志。

返回：

返回一个VkResult类型的错误码，具体返回类型如下：

返回VK_SUCCESS，表示执行成功。

返回VK_ERROR_INITIALIZATION_FAILED，表示入参异常。

[h2]vkQueueSignalReleaseImageOHOS()

VKAPI_ATTR VkResult VKAPI_CALL vkQueueSignalReleaseImageOHOS (VkQueue queue, uint32_t waitSemaphoreCount, const VkSemaphore* pWaitSemaphores, VkImage image, int32_t* pNativeFenceFd )

描述

当前图像使用完毕后，通过该函数向系统硬件缓冲区发出释放信号, 以便其他组件可以访问该图像。

系统能力： SystemCapability.Graphic.Vulkan

起始版本： 10

参数:

名称 描述
queue Vulkan队列的句柄。
waitSemaphoreCount 等待Semaphore(信号量)的数量。
pWaitSemaphores 指向等待Semaphore(信号量)数组的指针。
images 要释放的Vulkan图像句柄。
pNativeFenceFd 指向Fence的文件描述符的指针。

返回：

返回一个VkResult类型的错误码，具体返回类型如下：

返回VK_SUCCESS，表示执行成功。

返回VK_ERROR_DEVICE_LOST，表示Vulkan设备链接丢失。

返回VK_ERROR_OUT_OF_HOST_MEMORY，表示主机内存不足。

变量说明

[h2]allocationSize

VkDeviceSize VkNativeBufferPropertiesOHOS::allocationSize

描述:

占用的内存大小。

[h2]buffer

struct OH_NativeBuffer* VkImportNativeBufferInfoOHOS::buffer

描述:

OH_NativeBuffer结构体的指针。

[h2]externalFormat [1/2]

uint64_t VkNativeBufferFormatPropertiesOHOS::externalFormat

描述:

外部定义的格式标识符。

[h2]externalFormat [2/2]

uint64_t VkExternalFormatOHOS::externalFormat

描述:

外部定义的格式标识符。

[h2]flags

VkSurfaceCreateFlagsOHOS VkSurfaceCreateInfoOHOS::flags

描述:

预留的标志类型参数。

[h2]format

VkFormat VkNativeBufferFormatPropertiesOHOS::format

描述:

格式说明。

[h2]formatFeatures

VkFormatFeatureFlags VkNativeBufferFormatPropertiesOHOS::formatFeatures

描述:

描述了与externalFormat对应的能力。

[h2]memory

VkDeviceMemory VkMemoryGetNativeBufferInfoOHOS::memory

描述:

VkDeviceMemory对象。

[h2]memoryTypeBits

uint32_t VkNativeBufferPropertiesOHOS::memoryTypeBits

描述:

内存类型。

[h2]OHOSNativeBufferUsage

uint64_t VkNativeBufferUsageOHOS::OHOSNativeBufferUsage

描述:

NativeBuffer的用途说明。

[h2]pNext [1/7]

const void* VkSurfaceCreateInfoOHOS::pNext

描述:

下一级结构体指针。

[h2]pNext [2/7]

void* VkNativeBufferUsageOHOS::pNext

描述:

下一级结构体指针。

[h2]pNext [3/7]

void* VkNativeBufferPropertiesOHOS::pNext

描述:

下一级结构体指针。

[h2]pNext [4/7]

void* VkNativeBufferFormatPropertiesOHOS::pNext

描述:

下一级结构体指针。

[h2]pNext [5/7]

const void* VkImportNativeBufferInfoOHOS::pNext

描述:

下一级结构体指针。

[h2]pNext [6/7]

const void* VkMemoryGetNativeBufferInfoOHOS::pNext

描述:

下一级结构体指针。

[h2]pNext [7/7]

void* VkExternalFormatOHOS::pNext

描述:

下一级结构体指针。

[h2]samplerYcbcrConversionComponents

VkComponentMapping VkNativeBufferFormatPropertiesOHOS::samplerYcbcrConversionComponents

描述:

表示一组VkComponentSwizzle。

[h2]sType [1/7]

VkStructureType VkSurfaceCreateInfoOHOS::sType

描述:

结构体类型。

[h2]sType [2/7]

VkStructureType VkNativeBufferUsageOHOS::sType

描述:

结构体类型。

[h2]sType [3/7]

VkStructureType VkNativeBufferPropertiesOHOS::sType

描述:

结构体类型。

[h2]sType [4/7]

VkStructureType VkNativeBufferFormatPropertiesOHOS::sType

描述:

结构体类型。

[h2]sType [5/7]

VkStructureType VkImportNativeBufferInfoOHOS::sType

描述:

结构体类型。

[h2]sType [6/7]

VkStructureType VkMemoryGetNativeBufferInfoOHOS::sType

描述:

结构体类型。

[h2]sType [7/7]

VkStructureType VkExternalFormatOHOS::sType

描述:

结构体类型。

[h2]suggestedXChromaOffset

VkChromaLocation VkNativeBufferFormatPropertiesOHOS::suggestedXChromaOffset

描述:

X色度偏移。

[h2]suggestedYcbcrModel

VkSamplerYcbcrModelConversion VkNativeBufferFormatPropertiesOHOS::suggestedYcbcrModel

描述:

色彩模型。

[h2]suggestedYcbcrRange

VkSamplerYcbcrRange VkNativeBufferFormatPropertiesOHOS::suggestedYcbcrRange

描述:

色彩数值范围。

[h2]suggestedYChromaOffset

VkChromaLocation VkNativeBufferFormatPropertiesOHOS::suggestedYChromaOffset

描述:

Y色度偏移。

[h2]window

OHNativeWindow* VkSurfaceCreateInfoOHOS::window

描述:

OHNativeWindow指针。