1# OH_NativeImage 2 3 4## 概述 5 6提供NativeImage功能，作为数据消费者，主要用来将数据和OpenGL纹理对接，需在OpenGL环境下使用。 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 196### OH_ConsumerSurface_SetDefaultUsage() 197 198``` 199int32_t OH_ConsumerSurface_SetDefaultUsage (OH_NativeImage* image, uint64_t usage ) 200``` 201 202**描述** 203 204设置默认读写方式。 本接口为非线程安全类型接口。 205 206**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 207 208**起始版本：** 13 209 210**参数:** 211 212| 名称 | 描述 | 213| -------- | -------- | 214| image | 指向**OH_NativeImage**实例的指针。 | 215| usage | 表示读写方式。枚举值参考**OH_NativeBuffer_Usage**。 | 216 217**返回：** 218 219执行成功时返回NATIVE_ERROR_OK。 220 221image是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 222 223 224### OH_ConsumerSurface_SetDefaultSize() 225 226``` 227int32_t OH_ConsumerSurface_SetDefaultSize (OH_NativeImage* image, int32_t width, int32_t height ) 228``` 229 230**描述** 231 232设置几何图形默认尺寸。 本接口为非线程安全类型接口。 233 234**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 235 236**起始版本：** 13 237 238**参数:** 239 240| 名称 | 描述 | 241| -------- | -------- | 242| image | 指向**OH_NativeImage**实例的指针。 | 243| width | 表示几何图形宽度，取值范围大于0，单位为像素。 | 244| height | 表示几何图形高度，取值范围大于0，单位为像素。 | 245 246**返回：** 247 248执行成功时返回NATIVE_ERROR_OK。 249 250image是空指针时，或width、height小于等于0时返回NATIVE_ERROR_INVALID_ARGUMENTS。 251 252 253 254### OH_ConsumerSurface_Create() 255 256``` 257OH_NativeImage* OH_ConsumerSurface_Create () 258``` 259 260**描述** 261 262创建一个**OH_NativeImage**实例，作为surface的消费端。 263 264本接口仅用于surface消费端的内存轮转，创建的OH_NativeImage内部不会主动进行内存渲染处理。 265 266本接口不能与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口同时使用。 267 268本接口与 OH_NativeImage_AcquireNativeWindowBuffer和OH_NativeImage_ReleaseNativeWindowBuffer配合使用。 269 270本接口需要和[OH_NativeImage_Destroy](#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。 271 272本接口为非线程安全类型接口。 273 274**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 275 276**起始版本：** 12 277 278**返回：** 279 280成功则返回一个指向**OH_NativeImage**实例的指针，否则返回**NULL**。 281 282 283### OH_NativeImage_AcquireNativeWindowBuffer() 284 285``` 286int32_t OH_NativeImage_AcquireNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd ) 287``` 288 289**描述** 290 291通过消费端的**OH_NativeImage**获取一个**OHNativeWindowBuffer**。 292 293本接口不能与[OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage)接口同时使用。 294 295本接口将会创建一个**OHNativeWindowBuffer**。 296 297当使用**OHNativeWindowBuffer**时，用户需要通过**OH_NativeWindow_NativeObjectReference**接口将其引用计数加一。 298 299当**OHNativeWindowBuffer**使用完，用户需要通过**OH_NativeWindow_NativeObjectUnreference**接口将其引用计数减一。 300 301本接口需要和[OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer)接口配合使用，否则会存在内存泄露。 302 303当fenceFd使用完，用户需要将其close。 304本接口为非线程安全类型接口。 305 306**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 307 308**起始版本：** 12 309 310**参数:** 311 312| 名称 | 描述 | 313| -------- | -------- | 314| image | 指向**OH_NativeImage**实例的指针。 | 315| nativeWindowBuffer | 指向**OHNativeWindowBuffer**指针的指针。 | 316| fenceFd | 指向文件描述符句柄的指针。 | 317 318**返回：** 319 320执行成功时返回NATIVE_ERROR_OK。 321 322image, nativeWindowBuffer, fenceFd是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 323 324没有buffer可以消费时返回NATIVE_ERROR_NO_BUFFER。 325 326 327### OH_NativeImage_ReleaseNativeWindowBuffer() 328 329``` 330int32_t OH_NativeImage_ReleaseNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd ) 331``` 332 333**描述** 334 335通过**OH_NativeImage**实例将**OHNativeWindowBuffer**归还到buffer队列中。 336 337系统会将fenFd关闭，无需用户close。 338本接口为非线程安全类型接口。 339 340**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 341 342**起始版本：** 12 343 344**参数:** 345 346| 名称 | 描述 | 347| -------- | -------- | 348| image | 指向**OH_NativeImage**实例的指针。 | 349| nativeWindowBuffer | 指向**OHNativeWindowBuffer**实例的指针。 | 350| fenceFd | 指向文件描述符句柄, 用于并发同步控制。 | 351 352**返回：** 353 354执行成功时返回NATIVE_ERROR_OK。 355 356image或nativeWindowBuffer是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 357 358nativeWindowBuffer为状态非法时返回NATIVE_ERROR_BUFFER_STATE_INVALID。 359 360nativeWindowBuffer不在缓存中返回NATIVE_ERROR_BUFFER_NOT_IN_CACHE。 361 362 363 364### OH_NativeImage_AcquireNativeWindow() 365 366``` 367OHNativeWindow* OH_NativeImage_AcquireNativeWindow (OH_NativeImage * image) 368``` 369 370**描述** 371 372获取与OH_NativeImage相关联的OHNativeWindow指针。 373 374本接口为非线程安全类型接口。 375 376OH_NativeImage析构时会将对应的OHNativeWindow实例释放。若从本接口获取OHNativeWindow指针，当OH_NativeImage实例释放时，请将获取到的OHNativeWindow指针置空，防止后续产生野指针。 377 378 379**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 380 381**起始版本：** 9 382 383**参数:** 384 385| 名称 | 描述 | 386| -------- | -------- | 387| image | 是指向**OH_NativeImage**实例的指针。 | 388 389**返回：** 390 391成功则返回一个指向OHNativeWindow实例的指针，否则返回**NULL**。 392 393 394### OH_NativeImage_AttachContext() 395 396``` 397int32_t OH_NativeImage_AttachContext (OH_NativeImage * image, uint32_t textureId ) 398``` 399 400**描述** 401 402将OH_NativeImage实例附加到当前OpenGL ES上下文, 且该OpenGL ES纹理会绑定到 403 404GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新。 405本接口为非线程安全类型接口。 406 407**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 408 409**起始版本：** 9 410 411**参数:** 412 413| 名称 | 描述 | 414| -------- | -------- | 415| image | 是指向**OH_NativeImage**实例的指针。 | 416| textureId | 是OH_NativeImage要附加到的OpenGL ES纹理的id。 | 417 418**返回：** 419 420返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 421 422 423### OH_NativeImage_Create() 424 425``` 426OH_NativeImage* OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget ) 427``` 428 429**描述** 430 431创建一个**OH_NativeImage**实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。 432本接口需要与OH_NativeImage_Destroy接口配合使用，否则会存在内存泄露。 433本接口为非线程安全类型接口。 434 435**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 436 437**起始版本：** 9 438 439**参数:** 440 441| 名称 | 描述 | 442| -------- | -------- | 443| textureId | OpenGL ES的纹理ID，OH_NativeImage实例会与之相关联。 | 444| textureTarget | OpenGL ES的纹理目标。 | 445 446**返回：** 447 448返回一个指向**OH_NativeImage**实例的指针 returns **NULL** otherwise。 449 450 451### OH_NativeImage_Destroy() 452 453``` 454void OH_NativeImage_Destroy (OH_NativeImage ** image) 455``` 456 457**描述** 458 459销毁通过OH_NativeImage_Create创建的**OH_NativeImage**实例, 销毁后该 460 461**OH_NativeImage**指针会被赋值为空。 462本接口为非线程安全类型接口。 463 464**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 465 466**起始版本：** 9 467 468**参数:** 469 470| 名称 | 描述 | 471| -------- | -------- | 472| image | 是指向**OH_NativeImage**实例的指针。 | 473 474 475### OH_NativeImage_DetachContext() 476 477``` 478int32_t OH_NativeImage_DetachContext (OH_NativeImage * image) 479``` 480 481**描述** 482 483将OH_NativeImage实例从当前OpenGL ES上下文分离。 484本接口为非线程安全类型接口。 485 486**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 487 488**起始版本：** 9 489 490**参数:** 491 492| 名称 | 描述 | 493| -------- | -------- | 494| image | 是指向**OH_NativeImage**实例的指针。 | 495 496**返回：** 497 498返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 499 500 501### OH_NativeImage_GetSurfaceId() 502 503``` 504int32_t OH_NativeImage_GetSurfaceId (OH_NativeImage * image, uint64_t * surfaceId ) 505``` 506 507**描述** 508 509获取OH_NativeImage的surface编号。 510本接口为非线程安全类型接口。 511 512**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 513 514**起始版本：** 11 515 516**参数:** 517 518| 名称 | 描述 | 519| -------- | -------- | 520| image | 是指向**OH_NativeImage**实例的指针。 | 521| surfaceId | 是指向surface编号的指针。 | 522 523**返回：** 524 525返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 526 527 528### OH_NativeImage_GetTimestamp() 529 530``` 531int64_t OH_NativeImage_GetTimestamp (OH_NativeImage * image) 532``` 533 534**描述** 535 536获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。 537本接口为非线程安全类型接口。 538 539**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 540 541**起始版本：** 9 542 543**参数:** 544 545| 名称 | 描述 | 546| -------- | -------- | 547| image | 是指向**OH_NativeImage**实例的指针。 | 548 549**返回：** 550 551返回纹理图像的相关时间戳。 552 553 554### OH_NativeImage_GetTransformMatrix() 555 556``` 557int32_t OH_NativeImage_GetTransformMatrix (OH_NativeImage * image, float matrix[16] ) 558``` 559 560**描述** 561 562获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 563 564**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 565 566**废弃版本：** 12 567 568**替代接口：** [OH_NativeImage_GetTransformMatrixV2](#oh_nativeimage_gettransformmatrixv2) 569 570**起始版本：** 9 571 572**参数:** 573 574| 名称 | 描述 | 575| -------- | -------- | 576| image | 是指向**OH_NativeImage**实例的指针。 | 577| matrix | 用来存储要获取的4\*4的变化矩阵。 | 578 579**返回：** 580 581返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 582 583### OH_NativeImage_GetTransformMatrixV2() 584 585``` 586int32_t OH_NativeImage_GetTransformMatrixV2 (OH_NativeImage* image, float matrix[16] ) 587``` 588**描述** 589根据生产端设置的旋转角度，获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 590matrix在OH_NativeImage_UpdateSurfaceImage接口调用后，才会更新。 591本接口为非线程安全类型接口。 592 593**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 594 595**起始版本：** 12 596 597**参数:** 598 599| 名称 | 描述 | 600| -------- | -------- | 601| image | 是指向**OH_NativeImage**实例的指针。 | 602| matrix | 用来存储要获取的4\*4的变化矩阵。 | 603 604**返回：** 605 606返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 607 608### OH_NativeImage_SetOnFrameAvailableListener() 609 610``` 611int32_t OH_NativeImage_SetOnFrameAvailableListener (OH_NativeImage * image, OH_OnFrameAvailableListener listener ) 612``` 613 614**描述** 615 616设置帧可用回调。 617不允许在回调函数中调用本模块的其他接口。 618本接口为非线程安全类型接口。 619 620**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 621 622**起始版本：** 11 623 624**参数:** 625 626| 名称 | 描述 | 627| -------- | -------- | 628| image | 是指向**OH_NativeImage**实例的指针。 | 629| listener | 表示回调监听者。 | 630 631**返回：** 632 633返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 634 635 636### OH_NativeImage_UnsetOnFrameAvailableListener() 637 638``` 639int32_t OH_NativeImage_UnsetOnFrameAvailableListener (OH_NativeImage * image) 640``` 641 642**描述** 643 644取消设置帧可用回调。 645本接口为非线程安全类型接口。 646 647**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 648 649**起始版本：** 11 650 651**参数:** 652 653| 名称 | 描述 | 654| -------- | -------- | 655| image | 是指向**OH_NativeImage**实例的指针。 | 656 657**返回：** 658 659返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 660 661 662### OH_NativeImage_UpdateSurfaceImage() 663 664``` 665int32_t OH_NativeImage_UpdateSurfaceImage (OH_NativeImage * image) 666``` 667 668**描述** 669 670通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。 671本接口需要在Opengl ES环境上下文的线程中调用。 672本接口需要在接收到OH_OnFrameAvailableListener回调后调用。 673本接口为非线程安全类型接口。 674 675**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 676 677**起始版本：** 9 678 679**参数:** 680 681| 名称 | 描述 | 682| -------- | -------- | 683| image | 是指向**OH_NativeImage**实例的指针。 | 684 685**返回：** 686 687返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 688