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