harmony 鸿蒙native_image.h

  • 2025-06-12
  • 浏览 (4)

native_image.h

概述

定义获取和使用NativeImage的相关函数。

相关示例:NDKNativeImage

引用文件:

库: libnative_image.so

起始版本: 9

相关模块: OH_NativeImage

汇总

结构体

|名称|typedef关键字|描述| |–|–|–| |OH_OnFrameAvailableListener|OH_OnFrameAvailableListener|一个OH_NativeImage的监听者,通过OH_NativeImage_SetOnFrameAvailableListener接口注册该监听结构体,当有buffer可获取时,将触发回调给用户。| |OH_NativeImage|OH_NativeImage|提供OH_NativeImage结构体声明。| |NativeWindow|OHNativeWindow|提供对NativeWindow的访问功能。| |NativeWindowBuffer|OHNativeWindowBuffer|提供NativeWindowBuffer结构体声明。|

函数

|名称|typedef关键字|描述| |–|–|–| |typedef void (*OH_OnFrameAvailable)(void *context)|OH_OnFrameAvailable|有buffer可获取时触发的回调函数。| |OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget)|-|创建一个OH_NativeImage实例,该实例与OpenGL ES的纹理ID和纹理目标相关联。
本接口需要与OH_NativeImage_Destroy接口配合使用,否则会存在内存泄露。
本接口为非线程安全类型接口。| |OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image)|-|获取与OH_NativeImage相关联的OHNativeWindow指针。
本接口为非线程安全类型接口。
OH_NativeImage析构时会将对应的OHNativeWindow实例释放。若从本接口获取OHNativeWindow指针,当OH_NativeImage实例释放时,请将获取到的OHNativeWindow指针置空,防止后续产生野指针。| |int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId)|-|将OH_NativeImage实例附加到当前OpenGL ES上下文,且该OpenGL ES纹理会绑定到GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_DetachContext(OH_NativeImage* image)|-|将OH_NativeImage实例从当前OpenGL ES上下文分离。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image)|-|通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。
本接口需要在Opengl ES环境上下文的线程中调用。
本接口需要在接收到OH_OnFrameAvailableListener回调后调用。
本接口为非线程安全类型接口。| |int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image)|-|获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16])|-|获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。| |int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId)|-|获取OH_NativeImage的surface编号。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener)|-|设置帧可用回调。
不允许在回调函数中调用本模块的其他接口。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image)|-|取消设置帧可用回调。
本接口为非线程安全类型接口。| |void OH_NativeImage_Destroy(OH_NativeImage** image)|-|销毁通过OH_NativeImage_Create创建的OH_NativeImage实例, 销毁后该
OH_NativeImage指针会被赋值为空。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16])|-|根据生产端设置的旋转角度,获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。
matrix在OH_NativeImage_UpdateSurfaceImage接口调用后,才会更新。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_GetBufferMatrix(OH_NativeImage* image, float matrix[16])|-|获取根据生产端设置的旋转角度和buffer实际有效内容区域计算出的变换矩阵。
本接口返回一个变换矩阵,该矩阵是OH_NativeImage在消费buffer,即调用OH_NativeImage_UpdateSurfaceImage或者OH_NativeImage_AcquireNativeWindowBuffer时,根据buffer的旋转角度和实际有效内容区域计算所得。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd)|-|通过消费端的OH_NativeImage获取一个OHNativeWindowBuffer。
本接口不能与OH_NativeImage_UpdateSurfaceImage接口同时使用。
本接口将会创建一个OHNativeWindowBuffer。
当使用OHNativeWindowBuffer时,用户需要通过OH_NativeWindow_NativeObjectReference接口将其引用计数加一。
当OHNativeWindowBuffer使用完,用户需要通过OH_NativeWindow_NativeObjectUnreference接口将其引用计数减一。
本接口需要和OH_NativeImage_ReleaseNativeWindowBuffer接口配合使用,否则会存在内存泄露。
当fenceFd使用完,用户需要将其close。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd)|-|通过OH_NativeImage实例将OHNativeWindowBuffer归还到buffer队列中。
系统会将fenceFd关闭,无需用户close。
本接口为非线程安全类型接口。| |OH_NativeImage* OH_ConsumerSurface_Create(void)|-|创建一个OH_NativeImage实例,作为surface的消费端。
本接口仅用于surface消费端的内存轮转,创建的OH_NativeImage内部不会主动进行内存渲染处理。
本接口不能与OH_NativeImage_UpdateSurfaceImage接口同时使用。
本接口与OH_NativeImage_AcquireNativeWindowBufferOH_NativeImage_ReleaseNativeWindowBuffer配合使用。
本接口需要和OH_NativeImage_Destroy接口配合使用,否则会存在内存泄露。
本接口为非线程安全类型接口。| |int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage)|-|设置默认读写方式。
本接口为非线程安全类型接口。| |int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height)|-|设置几何图形默认尺寸。
本接口为非线程安全类型接口。| |int32_t OH_NativeImage_SetDropBufferMode(OH_NativeImage* image, bool isOpen)|-|设置OH_NativeImage是否为渲染丢帧模式。
处于此模式时,大部分生产端生产的buffer将会被丢弃,最新的buffer会及时上屏渲染。
此模式不能同时保证帧率高的要求。
此接口建议在OH_NativeImage_Create接口调用后立即调用。
此接口在与OH_NativeImage_UpdateSurfaceImage接口一起使用的场景下才会生效。
本接口为非线程安全类型接口。
|

函数说明

OH_OnFrameAvailable()

typedef void (*OH_OnFrameAvailable)(void *context)

描述

有buffer可获取时触发的回调函数。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 11

参数:

|参数项|描述| |–|–| |void *context|用户自定义的上下文信息,会在回调触发时返回给用户。|

OH_NativeImage_Create()

OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget)

描述

创建一个OH_NativeImage实例,该实例与OpenGL ES的纹理ID和纹理目标相关联。
本接口需要与OH_NativeImage_Destroy接口配合使用,否则会存在内存泄露。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

参数:

|参数项|描述| |–|–| |uint32_t textureId|OpenGL ES的纹理ID,OH_NativeImage实例会与之相关联。| |uint32_t textureTarget|OpenGL ES的纹理目标。|

返回:

|类型|说明| |–|–| |OH_NativeImage*|创建成功则返回一个指向OH_NativeImage实例的指针,否则返回NULL。|

OH_NativeImage_AcquireNativeWindow()

OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image)

描述

获取与OH_NativeImage相关联的OHNativeWindow指针。
本接口为非线程安全类型接口。
OH_NativeImage析构时会将对应的OHNativeWindow实例释放。若从本接口获取OHNativeWindow指针,当OH_NativeImage实例释放时,请将获取到的OHNativeWindow指针置空,防止后续产生野指针。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。|

返回:

|类型|说明| |–|–| |OHNativeWindow*|成功则返回一个指向OHNativeWindow实例的指针,否则返回NULL。|

OH_NativeImage_AttachContext()

int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId)

描述

将OH_NativeImage实例附加到当前OpenGL ES上下文,且该OpenGL ES纹理会绑定到GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |uint32_t textureId|是OH_NativeImage要附加到的OpenGL ES纹理的id。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_DetachContext()

int32_t OH_NativeImage_DetachContext(OH_NativeImage* image)

描述

将OH_NativeImage实例从当前OpenGL ES上下文分离。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_UpdateSurfaceImage()

int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image)

描述

通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。
本接口需要在Opengl ES环境上下文的线程中调用。
本接口需要在接收到OH_OnFrameAvailableListener回调后调用。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_GetTimestamp()

int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image)

描述

获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。|

返回:

|类型|说明| |–|–| |int64_t|返回纹理图像的相关时间戳。|

OH_NativeImage_GetTransformMatrix()

int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16])

描述

获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

废弃版本: 从API version 12开始废弃。

替代接口: OH_NativeImage_GetTransformMatrixV2

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |matrix| 用来存储要获取的44的变化矩阵。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_GetSurfaceId()

int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId)

描述

获取OH_NativeImage的surface编号。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 11

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |uint64_t* surfaceId|是指向surface编号的指针。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_SetOnFrameAvailableListener()

int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener)

描述

设置帧可用回调。
不允许在回调函数中调用本模块的其他接口。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 11

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |OH_OnFrameAvailableListener listener|表示回调监听者。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_UnsetOnFrameAvailableListener()

int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image)

描述

取消设置帧可用回调。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 11

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_Destroy()

void OH_NativeImage_Destroy(OH_NativeImage** image)

描述

销毁通过OH_NativeImage_Create创建的OH_NativeImage实例, 销毁后该
OH_NativeImage指针会被赋值为空。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 9

参数:

|参数项|描述| |–|–| |OH_NativeImage** image|指向OH_NativeImage实例的指针。|

OH_NativeImage_GetTransformMatrixV2()

int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16])

描述

根据生产端设置的旋转角度,获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。
matrix在OH_NativeImage_UpdateSurfaceImage接口调用后,才会更新。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 12

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |matrix| 用来存储要获取的44的变化矩阵。|

返回:

|类型|说明| |–|–| |int32_t|返回值为0表示执行成功,其他返回值可参考OHNativeErrorCode。|

OH_NativeImage_GetBufferMatrix()

int32_t OH_NativeImage_GetBufferMatrix(OH_NativeImage* image, float matrix[16])

描述

获取根据生产端设置的旋转角度和buffer实际有效内容区域计算出的变换矩阵。
本接口返回一个变换矩阵,该矩阵是OH_NativeImage在消费buffer,即调用OH_NativeImage_UpdateSurfaceImage或者OH_NativeImage_AcquireNativeWindowBuffer时,根据buffer的旋转角度和实际有效内容区域计算所得。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 15

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |matrix| 用于存储获取的44变换矩阵。|

返回:

|类型|说明| |–|–| |int32_t|返回接口执行结果。NATIVE_ERROR_OK,表示接口执行成功。
返回NATIVE_ERROR_INVALID_ARGUMENTS,对应错误码为40001000,表示image参数为空。
返回NATIVE_ERROR_MEM_OPERATION_ERROR,对应错误码为30001000,表示内存操作错误,获取变换矩阵失败。|

OH_NativeImage_AcquireNativeWindowBuffer()

int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd)

描述

通过消费端的OH_NativeImage获取一个OHNativeWindowBuffer。本接口不能与OH_NativeImage_UpdateSurfaceImage接口同时使用。
本接口将会创建一个OHNativeWindowBuffer。当使用OHNativeWindowBuffer<时,用户需要通过OH_NativeWindow_NativeObjectReference接口将其引用计数加一。当OHNativeWindowBuffer使用完,用户需要通过OH_NativeWindow_NativeObjectUnreference接口将其引用计数减一。
本接口需要和OH_NativeImage_ReleaseNativeWindowBuffer接口配合使用,否则会存在内存泄露。
当fenceFd使用完,用户需要将其close。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 12

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |OHNativeWindowBuffer** nativeWindowBuffer|指向OHNativeWindowBuffer指针的指针。| |int* fenceFd|指向文件描述符句柄的指针。|

返回:

|类型|说明| |–|–| |int32_t|执行成功时返回NATIVE_ERROR_OK。
image, nativeWindowBuffer, fenceFd是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。
没有buffer可以消费时返回NATIVE_ERROR_NO_BUFFER。|

OH_NativeImage_ReleaseNativeWindowBuffer()

int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd)

描述

通过OH_NativeImage实例将OHNativeWindowBuffer归还到buffer队列中。
系统会将fenceFd关闭,无需用户close。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 12

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |OHNativeWindowBuffer* nativeWindowBuffer|指向OHNativeWindowBuffer实例的指针。| |int fenceFd|指向文件描述符句柄, 用于并发同步控制。|

返回:

|类型|说明| |–|–| |int32_t|执行成功时返回NATIVE_ERROR_OK。
image, nativeWindowBuffer是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。
nativeWindowBuffer为状态非法时返回NATIVE_ERROR_BUFFER_STATE_INVALID。
nativeWindowBuffer不在缓存中返回NATIVE_ERROR_BUFFER_NOT_IN_CACHE。|

OH_ConsumerSurface_Create()

OH_NativeImage* OH_ConsumerSurface_Create(void)

描述

创建一个OH_NativeImage实例,作为surface的消费端。
本接口仅用于surface消费端的内存轮转,创建的OH_NativeImage内部不会主动进行内存渲染处理。
本接口不能与OH_NativeImage_UpdateSurfaceImage接口同时使用。
本接口与OH_NativeImage_AcquireNativeWindowBufferOH_NativeImage_ReleaseNativeWindowBuffer配合使用。
本接口需要和OH_NativeImage_Destroy接口配合使用,否则会存在内存泄露。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 12

返回:

|类型|说明| |–|–| |OH_NativeImage*|成功则返回一个指向OH_NativeImage实例的指针,否则返回NULL。|

OH_ConsumerSurface_SetDefaultUsage()

int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage)

描述

设置默认读写方式。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 13

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |uint64_t usage|表示读写方式。枚举值参考OH_NativeBuffer_Usage。|

返回:

|类型|说明| |–|–| |int32_t|执行成功时返回NATIVE_ERROR_OK。
image是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。|

OH_ConsumerSurface_SetDefaultSize()

int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height)

描述

设置几何图形默认尺寸。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 13

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |int32_t width|表示几何图形宽度,取值范围大于0,单位为像素。| |int32_t height|表示几何图形高度,取值范围大于0,单位为像素。|

返回:

|类型|说明| |–|–| |int32_t|执行成功时返回NATIVE_ERROR_OK。
image是空指针时,或width、height小于等于0时返回NATIVE_ERROR_INVALID_ARGUMENTS。|

OH_NativeImage_SetDropBufferMode()

int32_t OH_NativeImage_SetDropBufferMode(OH_NativeImage* image, bool isOpen)

描述

设置OH_NativeImage是否为渲染丢帧模式。
处于此模式时,大部分生产端生产的buffer将会被丢弃,最新的buffer会及时上屏渲染。
此模式不能同时保证帧率高的要求。
此接口建议在OH_NativeImage_Create接口调用后立即调用。
此接口在与OH_NativeImage_UpdateSurfaceImage接口一起使用的场景下才会生效。
本接口为非线程安全类型接口。

系统能力: SystemCapability.Graphic.Graphic2D.NativeImage

起始版本: 17

参数:

|参数项|描述| |–|–| |OH_NativeImage* image|指向OH_NativeImage实例的指针。| |bool isOpen|是否设置渲染丢帧。true表示设置为渲染丢帧模式,false表示不设置。|

返回:

|类型|说明| |–|–| |int32_t|执行成功时返回NATIVE_ERROR_OK。
image是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。|

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkGraphics 2D(方舟2D图形服务)

harmony 鸿蒙buffer_common.h

harmony 鸿蒙buffer_handle.h

harmony 鸿蒙BufferHandle

harmony 鸿蒙ColorSpacePrimaries

harmony 鸿蒙DisplaySoloist_ExpectedRateRange

harmony 鸿蒙drawing_bitmap.h

harmony 鸿蒙drawing_brush.h

harmony 鸿蒙drawing_canvas.h

harmony 鸿蒙drawing_color_filter.h

0  赞