c4761ec4创建于 2025年5月26日历史提交

native_image.h

概述

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

库： libnative_image.so

起始版本： 9

相关模块：OH_NativeImage

汇总

结构体

名称	描述
OH_OnFrameAvailableListener	一个OH_NativeImage的监听者，通过OH_NativeImage_SetOnFrameAvailableListener接口注册，该监听结构体当有帧可用时，将触发回调。

类型定义

名称	描述
typedef struct OH_NativeImage OH_NativeImage	提供OH_NativeImage结构体声明。
typedef struct NativeWindow OHNativeWindow	提供对NativeWindow的访问功能。
typedef struct NativeWindowBuffer OHNativeWindowBuffer	提供NativeWindowBuffer结构体声明。
typedef void(* OH_OnFrameAvailable) (void *context)	有buffer可获取时触发的回调函数。
typedef struct OH_OnFrameAvailableListener OH_OnFrameAvailableListener	一个OH_NativeImage的监听者，通过OH_NativeImage_SetOnFrameAvailableListener接口注册该监听结构体，当有buffer可获取时，将触发回调给用户。
typedef enum OHNativeErrorCode OHNativeErrorCode	接口错误码说明（仅用于查询）。

枚举

名称	描述
OHNativeErrorCode { NATIVE_ERROR_OK = 0, NATIVE_ERROR_MEM_OPERATION_ERROR = 30001000, NATIVE_ERROR_INVALID_ARGUMENTS = 40001000, NATIVE_ERROR_NO_PERMISSION = 40301000, NATIVE_ERROR_NO_BUFFER = 40601000, NATIVE_ERROR_NO_CONSUMER = 41202000, NATIVE_ERROR_NOT_INIT = 41203000, NATIVE_ERROR_CONSUMER_CONNECTED = 41206000, NATIVE_ERROR_BUFFER_STATE_INVALID = 41207000, NATIVE_ERROR_BUFFER_IN_CACHE = 41208000, NATIVE_ERROR_BUFFER_QUEUE_FULL = 41209000, NATIVE_ERROR_BUFFER_NOT_IN_CACHE = 41210000, NATIVE_ERROR_CONSUMER_DISCONNECTED = 41211000,NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED = 41212000,NATIVE_ERROR_UNSUPPORTED = 50102000, NATIVE_ERROR_UNKNOWN = 50002000,NATIVE_ERROR_HDI_ERROR = 50007000,NATIVE_ERROR_BINDER_ERROR = 50401000, NATIVE_ERROR_EGL_STATE_UNKNOWN = 60001000, NATIVE_ERROR_EGL_API_FAILED = 60002000 }	接口错误码说明（仅用于查询）。

名称

描述

OHNativeErrorCode {
NATIVE_ERROR_OK = 0, NATIVE_ERROR_MEM_OPERATION_ERROR = 30001000, NATIVE_ERROR_INVALID_ARGUMENTS = 40001000, NATIVE_ERROR_NO_PERMISSION = 40301000, NATIVE_ERROR_NO_BUFFER = 40601000,
NATIVE_ERROR_NO_CONSUMER = 41202000, NATIVE_ERROR_NOT_INIT = 41203000, NATIVE_ERROR_CONSUMER_CONNECTED = 41206000, NATIVE_ERROR_BUFFER_STATE_INVALID = 41207000,
NATIVE_ERROR_BUFFER_IN_CACHE = 41208000, NATIVE_ERROR_BUFFER_QUEUE_FULL = 41209000, NATIVE_ERROR_BUFFER_NOT_IN_CACHE = 41210000, NATIVE_ERROR_CONSUMER_DISCONNECTED = 41211000,NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED = 41212000,NATIVE_ERROR_UNSUPPORTED = 50102000,
NATIVE_ERROR_UNKNOWN = 50002000,NATIVE_ERROR_HDI_ERROR = 50007000,NATIVE_ERROR_BINDER_ERROR = 50401000, NATIVE_ERROR_EGL_STATE_UNKNOWN = 60001000, NATIVE_ERROR_EGL_API_FAILED = 60002000
}

接口错误码说明（仅用于查询）。

函数

名称	描述
int32_t OH_NativeImage_SetDropBufferMode (OH_NativeImage *image, bool isOpen)	设置OH_NativeImage是否为渲染丢帧模式。处于此模式时，大部分生产端生产的buffer将会被丢弃，最新的buffer会及时上屏渲染。此模式不能同时保证帧率高的要求。此接口建议在OH_NativeImage_Create接口调用后立即调用。此接口在与OH_NativeImage_UpdateSurfaceImage接口一起使用的场景下才会生效。本接口为非线程安全类型接口。
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实际有效内容区域计算出的变换矩阵。
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 ()	创建一个OH_NativeImage实例，作为surface的消费端。本接口仅用于surface消费端的内存轮转，创建的OH_NativeImage内部不会主动进行内存渲染处理。本接口不能与OH_NativeImage_UpdateSurfaceImage接口同时使用。本接口与OH_NativeImage_AcquireNativeWindowBuffer和OH_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)	设置几何图形默认尺寸。本接口为非线程安全类型接口。