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