1# OH_NativeImage 2 3 4## 概述 5 6提供NativeImage功能，作为数据消费者，其中一种用法是将数据和OpenGL纹理对接，需在OpenGL环境下使用，另外一种用法是开发者自行获取buffer进行渲染处理。 7 8**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 9 10**起始版本：** 9 11 12 13## 汇总 14 15 16### 文件 17 18| 名称 | 描述 | 19| -------- | -------- | 20| [native_image.h](native__image_8h.md) | 定义获取和使用NativeImage的相关函数。 | 21 22 23### 结构体 24 25| 名称 | 描述 | 26| -------- | -------- | 27| [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) | 一个OH_NativeImage的监听者，通过OH_NativeImage_SetOnFrameAvailableListener接口注册，该监听结构体当有帧可用时，将触发回调。 | 28 29 30### 类型定义 31 32| 名称 | 描述 | 33| -------- | -------- | 34| typedef struct [OH_NativeImage](#oh_nativeimage-1) [OH_NativeImage](#oh_nativeimage-1) | 提供OH_NativeImage结构体声明。 | 35| typedef struct NativeWindow [OHNativeWindow](#ohnativewindow) | 提供对NativeWindow的访问功能。 | 36| typedef struct NativeWindowBuffer [OHNativeWindowBuffer](#ohnativewindowbuffer) | 提供NativeWindowBuffer结构体声明。 | 37| typedef void(\* [OH_OnFrameAvailable](#oh_onframeavailable)) (void \*context) | 有buffer可获取时触发的回调函数。 | 38| typedef struct [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) [OH_OnFrameAvailableListener](#oh_onframeavailablelistener) | 一个OH_NativeImage的监听者，通过[OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener)接口注册 该监听结构体，当有buffer可获取时，将触发回调给用户。 | 39| typedef enum [OHNativeErrorCode](#ohnativeerrorcode) [OHNativeErrorCode](#ohnativeerrorcode) | 接口错误码说明（仅用于查询）。 | 40 41### 枚举 42 43| 名称 | 描述 | 44| -------- | -------- | 45| [OHNativeErrorCode](#ohnativeerrorcode-1) {<br/>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,<br/>NATIVE_ERROR_NO_CONSUMER = 41202000, NATIVE_ERROR_NOT_INIT = 41203000, NATIVE_ERROR_CONSUMER_CONNECTED = 41206000, NATIVE_ERROR_BUFFER_STATE_INVALID = 41207000,<br/>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,<br/>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<br/>} | 接口错误码说明（仅用于查询）。 | 46 47### 函数 48 49| 名称 | 描述 | 50| -------- | -------- | 51| int32_t [OH_NativeImage_SetDropBufferMode](#oh_nativeimage_setdropbuffermode) ([OH_NativeImage](#oh_nativeimage) \*image, bool isOpen) | 设置OH_NativeImage是否为渲染丢帧模式。<br/>处于此模式时，大部分生产端生产的buffer将会被丢弃，最新的buffer会及时上屏渲染。<br/>此模式不能同时保证帧率高的要求。<br/>此接口建议在[OH_NativeImage_Create](#oh_nativeimage_create)接口调用后立即调用。<br/>此接口在与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口一起使用的场景下才会生效。<br/>本接口为非线程安全类型接口。 | 52| [OH_NativeImage](#oh_nativeimage-1) \* [OH_NativeImage_Create](#oh_nativeimage_create) (uint32_t textureId, uint32_t textureTarget) | 创建一个**OH_NativeImage**实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。<br/>本接口需要与[OH_NativeImage_Destroy](#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。<br/>本接口为非线程安全类型接口。 | 53| [OHNativeWindow](_native_window.md#ohnativewindow) \* [OH_NativeImage_AcquireNativeWindow](#oh_nativeimage_acquirenativewindow) ([OH_NativeImage](#oh_nativeimage-1) \*image) | 获取与OH_NativeImage相关联的OHNativeWindow指针。<br/>本接口为非线程安全类型接口。<br/>OH_NativeImage析构时会将对应的OHNativeWindow实例释放。若从本接口获取OHNativeWindow指针，当OH_NativeImage实例释放时，请将获取到的OHNativeWindow指针置空，防止后续产生野指针。 | 54| int32_t [OH_NativeImage_AttachContext](#oh_nativeimage_attachcontext) ([OH_NativeImage](#oh_nativeimage-1) \*image, uint32_t textureId) | 将OH_NativeImage实例附加到当前OpenGL ES上下文，且该OpenGL ES纹理会绑定到GL_TEXTURE_EXTERNAL_OES，并通过OH_NativeImage进行更新。<br>本接口为非线程安全类型接口。 | 55| int32_t [OH_NativeImage_DetachContext](#oh_nativeimage_detachcontext) ([OH_NativeImage](#oh_nativeimage-1) \*image) | 将OH_NativeImage实例从当前OpenGL ES上下文分离。<br/>本接口为非线程安全类型接口。 | 56| int32_t [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage) ([OH_NativeImage](#oh_nativeimage-1) \*image) | 通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。<br/>本接口需要在Opengl ES环境上下文的线程中调用。<br/>本接口需要在接收到[OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md)回调后调用。<br/>本接口为非线程安全类型接口。 | 57| int64_t [OH_NativeImage_GetTimestamp](#oh_nativeimage_gettimestamp) ([OH_NativeImage](#oh_nativeimage-1) \*image) | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。<br/>本接口为非线程安全类型接口。 | 58| int32_t [OH_NativeImage_GetTransformMatrix](#oh_nativeimage_gettransformmatrix) ([OH_NativeImage](#oh_nativeimage-1) \*image, float matrix[16]) | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 | 59| int32_t [OH_NativeImage_GetSurfaceId](#oh_nativeimage_getsurfaceid) ([OH_NativeImage](#oh_nativeimage-1) \*image, uint64_t \*surfaceId) | 获取OH_NativeImage的surface编号。<br/>本接口为非线程安全类型接口。 | 60| int32_t [OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener) ([OH_NativeImage](#oh_nativeimage-1) \*image, [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) listener) | 设置帧可用回调。<br/>不允许在回调函数中调用本模块的其他接口。<br/>本接口为非线程安全类型接口。 | 61| int32_t [OH_NativeImage_UnsetOnFrameAvailableListener](#oh_nativeimage_unsetonframeavailablelistener) ([OH_NativeImage](#oh_nativeimage-1) \*image) | 取消设置帧可用回调。<br/>本接口为非线程安全类型接口。 | 62| void [OH_NativeImage_Destroy](#oh_nativeimage_destroy) ([OH_NativeImage](#oh_nativeimage-1) \*\*image) | 销毁通过OH_NativeImage_Create创建的**OH_NativeImage**实例，销毁后该<br/>**OH_NativeImage**指针会被赋值为空。<br/>本接口为非线程安全类型接口。 | 63| int32_t [OH_NativeImage_GetTransformMatrixV2](#oh_nativeimage_gettransformmatrixv2) ([OH_NativeImage](#oh_nativeimage-1) \*image, float matrix[16]) | 根据生产端设置的旋转角度，获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。<br/>matrix在[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口调用后，才会更新。<br/>本接口为非线程安全类型接口。 | 64| int32_t [OH_NativeImage_GetBufferMatrix](#oh_nativeimage_getbuffermatrix) ([OH_NativeImage](#oh_nativeimage-1) \*image, float matrix[16]) | 获取根据生产端设置的旋转角度和buffer实际有效内容区域计算出的变换矩阵。 | 65| int32_t [OH_NativeImage_AcquireNativeWindowBuffer](#oh_nativeimage_acquirenativewindowbuffer) ([OH_NativeImage](#oh_nativeimage-1) \*image, [OHNativeWindowBuffer](_native_window.md#ohnativewindowbuffer) \*\*nativeWindowBuffer, int \*fenceFd) | 通过消费端的**OH_NativeImage**获取一个**OHNativeWindowBuffer**。<br/>本接口不能与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口同时使用。<br/>本接口将会创建一个**OHNativeWindowBuffer**。<br/>当使用**OHNativeWindowBuffer**时，用户需要通过[OH_NativeWindow_NativeObjectReference](_native_window.md#oh_nativewindow_nativeobjectreference)接口将其引用计数加一。<br/>当**OHNativeWindowBuffer**使用完，用户需要通过[OH_NativeWindow_NativeObjectUnreference](_native_window.md#oh_nativewindow_nativeobjectunreference)接口将其引用计数减一。<br/>本接口需要和[OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer)接口配合使用，否则会存在内存泄露。<br/>当fenceFd使用完，用户需要将其close。<br/>本接口为非线程安全类型接口。 | 66| int32_t [OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer) ([OH_NativeImage](#oh_nativeimage-1) \*image, [OHNativeWindowBuffer](_native_window.md#ohnativewindowbuffer) \*nativeWindowBuffer, int fenceFd) | 通过**OH_NativeImage**实例将**OHNativeWindowBuffer**归还到buffer队列中。<br/>系统会将fenFd关闭，无需用户close。<br/>本接口为非线程安全类型接口。 | 67| [OH_NativeImage](#oh_nativeimage-1) \* [OH_ConsumerSurface_Create](#oh_consumersurface_create) () | 创建一个**OH_NativeImage**实例，作为surface的消费端。<br/>本接口仅用于surface消费端的内存轮转，创建的OH_NativeImage内部不会主动进行内存渲染处理。<br/>本接口不能与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口同时使用。<br/>本接口与 OH_NativeImage_AcquireNativeWindowBuffer和OH_NativeImage_ReleaseNativeWindowBuffer配合使用。<br/>本接口需要和[OH_NativeImage_Destroy](#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。<br/>本接口为非线程安全类型接口。 | 68| int32_t [OH_ConsumerSurface_SetDefaultUsage](#oh_consumersurface_setdefaultusage) ([OH_NativeImage](#oh_nativeimage-1) \*image, uint64_t usage) | 设置默认读写方式。 本接口为非线程安全类型接口。 | 69| int32_t [OH_ConsumerSurface_SetDefaultSize](#oh_consumersurface_setdefaultsize) ([OH_NativeImage](#oh_nativeimage-1) \*image, int32_t width, int32_t height) | 设置几何图形默认尺寸。 本接口为非线程安全类型接口。 | 70 71## 类型定义说明 72 73 74### OH_NativeImage 75 76``` 77typedef struct OH_NativeImage OH_NativeImage 78``` 79 80**描述：** 81 82提供OH_NativeImage结构体声明。 83 84**起始版本：** 9 85 86 87### OH_OnFrameAvailable 88 89``` 90typedef void(* OH_OnFrameAvailable) (void *context) 91``` 92 93**描述：** 94 95有buffer可获取时触发的回调函数。 96 97**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 98 99**起始版本：** 11 100 101**参数:** 102 103| 名称 | 描述 | 104| -------- | -------- | 105| context | 用户自定义的上下文信息，会在回调触发时返回给用户。 | 106 107 108### OH_OnFrameAvailableListener 109 110``` 111typedef struct OH_OnFrameAvailableListener OH_OnFrameAvailableListener 112``` 113 114**描述：** 115 116一个OH_NativeImage的监听者，通过[OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener)接口注册，该监听结构体，当有buffer可获取时，将触发回调给用户。 117 118**起始版本：** 11 119 120 121### OHNativeErrorCode 122 123``` 124typedef enum OHNativeErrorCode OHNativeErrorCode 125``` 126**描述：** 127 128接口错误码说明（仅用于查询）。 129 130**起始版本：** 12 131 132 133### OHNativeWindow 134 135``` 136typedef struct NativeWindow OHNativeWindow 137``` 138 139**描述：** 140 141提供对NativeWindow的访问功能。 142 143**起始版本：** 9 144 145### OHNativeWindowBuffer 146 147``` 148typedef struct NativeWindowBuffer OHNativeWindowBuffer 149``` 150 151**描述：** 152 153提供NativeWindowBuffer结构体声明。 154 155**起始版本：** 12 156 157 158## 枚举类型说明 159 160 161### OHNativeErrorCode 162 163``` 164enum OHNativeErrorCode 165``` 166**描述：** 167 168接口错误码说明（仅用于查询）。 169 170**起始版本：** 12 171 172| 枚举值 | 描述 | 173| -------- | -------- | 174| NATIVE_ERROR_OK | 成功。 | 175| NATIVE_ERROR_MEM_OPERATION_ERROR<sup>15+</sup> | 内存操作错误。 | 176| NATIVE_ERROR_INVALID_ARGUMENTS | 入参无效。 | 177| NATIVE_ERROR_NO_PERMISSION | 无权限操作。 | 178| NATIVE_ERROR_NO_BUFFER | 无空闲可用的buffer。 | 179| NATIVE_ERROR_NO_CONSUMER | 消费端不存在。 | 180| NATIVE_ERROR_NOT_INIT | 未初始化。 | 181| NATIVE_ERROR_CONSUMER_CONNECTED | 消费端已经被连接。 | 182| NATIVE_ERROR_BUFFER_STATE_INVALID | buffer状态不符合预期。 | 183| NATIVE_ERROR_BUFFER_IN_CACHE | buffer已在缓存队列中。 | 184| NATIVE_ERROR_BUFFER_QUEUE_FULL | 队列已满。 | 185| NATIVE_ERROR_BUFFER_NOT_IN_CACHE | buffer不在缓存队列中。 | 186| NATIVE_ERROR_CONSUMER_DISCONNECTED | 消费端已经被断开连接。 | 187| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | 消费端未注册listener回调函数。 | 188| NATIVE_ERROR_UNSUPPORTED | 当前设备或平台不支持。 | 189| NATIVE_ERROR_UNKNOWN | 未知错误，请查看日志。 | 190| NATIVE_ERROR_HDI_ERROR | HDI接口调用失败。 | 191| NATIVE_ERROR_BINDER_ERROR | 跨进程通信失败。 | 192| NATIVE_ERROR_EGL_STATE_UNKNOWN | egl环境状态异常。 | 193| NATIVE_ERROR_EGL_API_FAILED | egl接口调用失败。 | 194 195 196## 函数说明 197 198### OH_NativeImage_SetDropBufferMode() 199 200``` 201int32_t OH_NativeImage_SetDropBufferMode (OH_NativeImage* image, bool isOpen ) 202``` 203 204**描述** 205 206设置OH_NativeImage是否为渲染丢帧模式。 207 208处于此模式时，大部分生产端生产的buffer将会被丢弃，最新的buffer会及时上屏渲染。 209 210此模式不能同时保证帧率高的要求。 211 212此接口建议在[OH_NativeImage_Create](#oh_nativeimage_create)接口调用后立即调用。 213 214此接口在与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口一起使用的场景下才会生效。 215 216本接口为非线程安全类型接口。 217 218**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 219 220**起始版本：** 17 221 222**参数:** 223 224| 名称 | 描述 | 225| -------- | -------- | 226| image | 指向OH_NativeImage实例的指针。 | 227| isOpen | 是否设置渲染丢帧。true表示设置为渲染丢帧模式，false表示不设置。 | 228 229**返回：** 230 231执行成功时返回NATIVE_ERROR_OK。 232 233image是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 234 235### OH_NativeImage_GetBufferMatrix() 236 237``` 238int32_t OH_NativeImage_GetBufferMatrix (OH_NativeImage* image, float matrix[16] ) 239``` 240 241**描述：** 242 243获取根据生产端设置的旋转角度和buffer实际有效内容区域计算出的变换矩阵。 244 245本接口返回一个变换矩阵，该矩阵是[OH_NativeImage](#oh_nativeimage-1)在消费buffer，即调用[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage) 或者[OH_NativeImage_AcquireNativeWindowBuffer](#oh_nativeimage_acquirenativewindowbuffer)时，根据buffer的旋转角度和实际有效内容区域计算所得。 246 247本接口为非线程安全类型接口。 248 249**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 250 251**起始版本：** 15 252 253**参数:** 254 255| 名称 | 描述 | 256| -------- | -------- | 257| image | 指向[OH_NativeImage](#oh_nativeimage-1)实例的指针。 | 258| matrix | 用于存储获取的4\*4变换矩阵。 | 259 260**返回：** 261 262返回接口执行结果。NATIVE_ERROR_OK，表示接口执行成功。 263 264返回NATIVE_ERROR_INVALID_ARGUMENTS，对应错误码为40001000，表示image参数为空。 265 266返回NATIVE_ERROR_MEM_OPERATION_ERROR，对应错误码为30001000，表示内存操作错误，获取变换矩阵失败。 267 268### OH_ConsumerSurface_SetDefaultUsage() 269 270``` 271int32_t OH_ConsumerSurface_SetDefaultUsage (OH_NativeImage* image, uint64_t usage ) 272``` 273 274**描述：** 275 276设置默认读写方式。 本接口为非线程安全类型接口。 277 278**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 279 280**起始版本：** 13 281 282**参数:** 283 284| 名称 | 描述 | 285| -------- | -------- | 286| image | 指向**OH_NativeImage**实例的指针。 | 287| usage | 表示读写方式。枚举值参考**OH_NativeBuffer_Usage**。 | 288 289**返回：** 290 291执行成功时返回NATIVE_ERROR_OK。 292 293image是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 294 295 296### OH_ConsumerSurface_SetDefaultSize() 297 298``` 299int32_t OH_ConsumerSurface_SetDefaultSize (OH_NativeImage* image, int32_t width, int32_t height ) 300``` 301 302**描述：** 303 304设置几何图形默认尺寸。 本接口为非线程安全类型接口。 305 306**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 307 308**起始版本：** 13 309 310**参数:** 311 312| 名称 | 描述 | 313| -------- | -------- | 314| image | 指向**OH_NativeImage**实例的指针。 | 315| width | 表示几何图形宽度，取值范围大于0，单位为像素。 | 316| height | 表示几何图形高度，取值范围大于0，单位为像素。 | 317 318**返回：** 319 320执行成功时返回NATIVE_ERROR_OK。 321 322image是空指针时，或width、height小于等于0时返回NATIVE_ERROR_INVALID_ARGUMENTS。 323 324 325 326### OH_ConsumerSurface_Create() 327 328``` 329OH_NativeImage* OH_ConsumerSurface_Create () 330``` 331 332**描述：** 333 334创建一个**OH_NativeImage**实例，作为surface的消费端。 335 336本接口仅用于surface消费端的内存轮转，创建的OH_NativeImage内部不会主动进行内存渲染处理。 337 338本接口不能与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口同时使用。 339 340本接口与 OH_NativeImage_AcquireNativeWindowBuffer和OH_NativeImage_ReleaseNativeWindowBuffer配合使用。 341 342本接口需要和[OH_NativeImage_Destroy](#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。 343 344本接口为非线程安全类型接口。 345 346**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 347 348**起始版本：** 12 349 350**返回：** 351 352成功则返回一个指向**OH_NativeImage**实例的指针，否则返回**NULL**。 353 354 355### OH_NativeImage_AcquireNativeWindowBuffer() 356 357``` 358int32_t OH_NativeImage_AcquireNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd ) 359``` 360 361**描述：** 362 363通过消费端的**OH_NativeImage**获取一个**OHNativeWindowBuffer**。 364 365本接口不能与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口同时使用。 366 367本接口将会创建一个**OHNativeWindowBuffer**。 368 369当使用**OHNativeWindowBuffer**时，用户需要通过**OH_NativeWindow_NativeObjectReference**接口将其引用计数加一。 370 371当**OHNativeWindowBuffer**使用完，用户需要通过**OH_NativeWindow_NativeObjectUnreference**接口将其引用计数减一。 372 373本接口需要和[OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer)接口配合使用，否则会存在内存泄露。 374 375当fenceFd使用完，用户需要将其close。 376本接口为非线程安全类型接口。 377 378**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 379 380**起始版本：** 12 381 382**参数:** 383 384| 名称 | 描述 | 385| -------- | -------- | 386| image | 指向**OH_NativeImage**实例的指针。 | 387| nativeWindowBuffer | 指向**OHNativeWindowBuffer**指针的指针。 | 388| fenceFd | 指向文件描述符句柄的指针。 | 389 390**返回：** 391 392执行成功时返回NATIVE_ERROR_OK。 393 394image，nativeWindowBuffer，fenceFd是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 395 396没有buffer可以消费时返回NATIVE_ERROR_NO_BUFFER。 397 398 399### OH_NativeImage_ReleaseNativeWindowBuffer() 400 401``` 402int32_t OH_NativeImage_ReleaseNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd ) 403``` 404 405**描述：** 406 407通过**OH_NativeImage**实例将**OHNativeWindowBuffer**归还到buffer队列中。 408 409系统会将fenFd关闭，无需用户close。 410本接口为非线程安全类型接口。 411 412**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 413 414**起始版本：** 12 415 416**参数:** 417 418| 名称 | 描述 | 419| -------- | -------- | 420| image | 指向**OH_NativeImage**实例的指针。 | 421| nativeWindowBuffer | 指向**OHNativeWindowBuffer**实例的指针。 | 422| fenceFd | 指向文件描述符句柄，用于并发同步控制。 | 423 424**返回：** 425 426执行成功时返回NATIVE_ERROR_OK。 427 428image或nativeWindowBuffer是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 429 430nativeWindowBuffer为状态非法时返回NATIVE_ERROR_BUFFER_STATE_INVALID。 431 432nativeWindowBuffer不在缓存中返回NATIVE_ERROR_BUFFER_NOT_IN_CACHE。 433 434 435 436### OH_NativeImage_AcquireNativeWindow() 437 438``` 439OHNativeWindow* OH_NativeImage_AcquireNativeWindow (OH_NativeImage * image) 440``` 441 442**描述：** 443 444获取与OH_NativeImage相关联的OHNativeWindow指针。 445 446本接口为非线程安全类型接口。 447 448OH_NativeImage析构时会将对应的OHNativeWindow实例释放。若从本接口获取OHNativeWindow指针，当OH_NativeImage实例释放时，请将获取到的OHNativeWindow指针置空，防止后续产生野指针。 449 450 451**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 452 453**起始版本：** 9 454 455**参数:** 456 457| 名称 | 描述 | 458| -------- | -------- | 459| image | 是指向**OH_NativeImage**实例的指针。 | 460 461**返回：** 462 463成功则返回一个指向OHNativeWindow实例的指针，否则返回**NULL**。 464 465 466### OH_NativeImage_AttachContext() 467 468``` 469int32_t OH_NativeImage_AttachContext (OH_NativeImage * image, uint32_t textureId ) 470``` 471 472**描述：** 473 474将OH_NativeImage实例附加到当前OpenGL ES上下文，且该OpenGL ES纹理会绑定到 475 476GL_TEXTURE_EXTERNAL_OES，并通过OH_NativeImage进行更新。 477本接口为非线程安全类型接口。 478 479**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 480 481**起始版本：** 9 482 483**参数:** 484 485| 名称 | 描述 | 486| -------- | -------- | 487| image | 是指向**OH_NativeImage**实例的指针。 | 488| textureId | 是OH_NativeImage要附加到的OpenGL ES纹理的id。 | 489 490**返回：** 491 492返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 493 494 495### OH_NativeImage_Create() 496 497``` 498OH_NativeImage* OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget ) 499``` 500 501**描述：** 502 503创建一个**OH_NativeImage**实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。 504本接口需要与OH_NativeImage_Destroy接口配合使用，否则会存在内存泄露。 505本接口为非线程安全类型接口。 506 507**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 508 509**起始版本：** 9 510 511**参数:** 512 513| 名称 | 描述 | 514| -------- | -------- | 515| textureId | OpenGL ES的纹理ID，OH_NativeImage实例会与之相关联。 | 516| textureTarget | OpenGL ES的纹理目标。 | 517 518**返回：** 519 520创建成功则返回一个指向**OH_NativeImage**实例的指针实例的指针，否则返回**NULL**。 521 522 523### OH_NativeImage_Destroy() 524 525``` 526void OH_NativeImage_Destroy (OH_NativeImage ** image) 527``` 528 529**描述：** 530 531销毁通过OH_NativeImage_Create创建的**OH_NativeImage**实例，销毁后该 532 533**OH_NativeImage**指针会被赋值为空。 534本接口为非线程安全类型接口。 535 536**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 537 538**起始版本：** 9 539 540**参数:** 541 542| 名称 | 描述 | 543| -------- | -------- | 544| image | 是指向**OH_NativeImage**实例的指针。 | 545 546 547### OH_NativeImage_DetachContext() 548 549``` 550int32_t OH_NativeImage_DetachContext (OH_NativeImage * image) 551``` 552 553**描述：** 554 555将OH_NativeImage实例从当前OpenGL ES上下文分离。 556本接口为非线程安全类型接口。 557 558**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 559 560**起始版本：** 9 561 562**参数:** 563 564| 名称 | 描述 | 565| -------- | -------- | 566| image | 是指向**OH_NativeImage**实例的指针。 | 567 568**返回：** 569 570返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 571 572 573### OH_NativeImage_GetSurfaceId() 574 575``` 576int32_t OH_NativeImage_GetSurfaceId (OH_NativeImage * image, uint64_t * surfaceId ) 577``` 578 579**描述：** 580 581获取OH_NativeImage的surface编号。 582本接口为非线程安全类型接口。 583 584**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 585 586**起始版本：** 11 587 588**参数:** 589 590| 名称 | 描述 | 591| -------- | -------- | 592| image | 是指向**OH_NativeImage**实例的指针。 | 593| surfaceId | 是指向surface编号的指针。 | 594 595**返回：** 596 597返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 598 599 600### OH_NativeImage_GetTimestamp() 601 602``` 603int64_t OH_NativeImage_GetTimestamp (OH_NativeImage * image) 604``` 605 606**描述：** 607 608获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。 609本接口为非线程安全类型接口。 610 611**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 612 613**起始版本：** 9 614 615**参数:** 616 617| 名称 | 描述 | 618| -------- | -------- | 619| image | 是指向**OH_NativeImage**实例的指针。 | 620 621**返回：** 622 623返回纹理图像的相关时间戳。 624 625 626### OH_NativeImage_GetTransformMatrix() 627 628``` 629int32_t OH_NativeImage_GetTransformMatrix (OH_NativeImage * image, float matrix[16] ) 630``` 631 632**描述：** 633 634获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 635 636**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 637 638**废弃版本：** 12 639 640**替代接口：** [OH_NativeImage_GetTransformMatrixV2](#oh_nativeimage_gettransformmatrixv2) 641 642**起始版本：** 9 643 644**参数:** 645 646| 名称 | 描述 | 647| -------- | -------- | 648| image | 是指向**OH_NativeImage**实例的指针。 | 649| matrix | 用来存储要获取的4\*4的变化矩阵。 | 650 651**返回：** 652 653返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 654 655### OH_NativeImage_GetTransformMatrixV2() 656 657``` 658int32_t OH_NativeImage_GetTransformMatrixV2 (OH_NativeImage* image, float matrix[16] ) 659``` 660**描述：** 661 662根据生产端设置的旋转角度，获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 663matrix在OH_NativeImage_UpdateSurfaceImage接口调用后，才会更新。 664本接口为非线程安全类型接口。 665 666**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 667 668**起始版本：** 12 669 670**参数:** 671 672| 名称 | 描述 | 673| -------- | -------- | 674| image | 是指向**OH_NativeImage**实例的指针。 | 675| matrix | 用来存储要获取的4\*4的变化矩阵。 | 676 677**返回：** 678 679返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 680 681### OH_NativeImage_SetOnFrameAvailableListener() 682 683``` 684int32_t OH_NativeImage_SetOnFrameAvailableListener (OH_NativeImage * image, OH_OnFrameAvailableListener listener ) 685``` 686 687**描述：** 688 689设置帧可用回调。 690不允许在回调函数中调用本模块的其他接口。 691本接口为非线程安全类型接口。 692 693**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 694 695**起始版本：** 11 696 697**参数:** 698 699| 名称 | 描述 | 700| -------- | -------- | 701| image | 是指向**OH_NativeImage**实例的指针。 | 702| listener | 表示回调监听者。 | 703 704**返回：** 705 706返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 707 708 709### OH_NativeImage_UnsetOnFrameAvailableListener() 710 711``` 712int32_t OH_NativeImage_UnsetOnFrameAvailableListener (OH_NativeImage * image) 713``` 714 715**描述：** 716 717取消设置帧可用回调。 718本接口为非线程安全类型接口。 719 720**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 721 722**起始版本：** 11 723 724**参数:** 725 726| 名称 | 描述 | 727| -------- | -------- | 728| image | 是指向**OH_NativeImage**实例的指针。 | 729 730**返回：** 731 732返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 733 734 735### OH_NativeImage_UpdateSurfaceImage() 736 737``` 738int32_t OH_NativeImage_UpdateSurfaceImage (OH_NativeImage * image) 739``` 740 741**描述：** 742 743通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。 744本接口需要在Opengl ES环境上下文的线程中调用。 745本接口需要在接收到OH_OnFrameAvailableListener回调后调用。 746本接口为非线程安全类型接口。 747 748**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 749 750**起始版本：** 9 751 752**参数:** 753 754| 名称 | 描述 | 755| -------- | -------- | 756| image | 是指向**OH_NativeImage**实例的指针。 | 757 758**返回：** 759 760返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 761