1# OH_NativeImage 2 3 4## Overview 5 6The OH_NativeImage module provides the capabilities of **NativeImage**. Functioning as a data consumer, it is used to associate data with the OpenGL texture. It is used in the OpenGL environment. Alternatively, you can directly obtain the buffer for custom rendering. 7 8**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 9 10**Since**: 9 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [native_image.h](native__image_8h.md) | Defines the functions for obtaining and using **NativeImage**.| 21 22 23### Structs 24 25| Name| Description| 26| -------- | -------- | 27| [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) | Defines an **OH_NativeImage** listener, which is registered through **OH_NativeImage_SetOnFrameAvailableListener**. The listener triggers a callback when a frame is available.| 28 29 30### Types 31 32| Name| Description| 33| -------- | -------- | 34| typedef struct [OH_NativeImage](#oh_nativeimage-1) [OH_NativeImage](#oh_nativeimage-1) | Provides the declaration of an **OH_NativeImage** struct. | 35| typedef struct NativeWindow [OHNativeWindow](#ohnativewindow) | Provides the capability of accessing the **NativeWindow**. | 36| typedef struct NativeWindowBuffer [OHNativeWindowBuffer](#ohnativewindowbuffer) | Provides the declaration of a **NativeWindowBuffer** struct.| 37| typedef void(\* [OH_OnFrameAvailable](#oh_onframeavailable)) (void \*context) | Defines the callback function triggered when a frame is available. | 38| typedef struct [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) [OH_OnFrameAvailableListener](#oh_onframeavailablelistener) | Defines an **OH_NativeImage** listener, which is registered through [OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener). The listener triggers a callback when a frame is available.| 39| typedef enum [OHNativeErrorCode](#ohnativeerrorcode) [OHNativeErrorCode](#ohnativeerrorcode) | Defines an enum for the error codes. | 40 41### Enums 42 43| Name| Description| 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>} | Enumerates the error codes. | 46 47### Functions 48 49| Name| Description| 50| -------- | -------- | 51| [OH_NativeImage](#oh_nativeimage-1) \* [OH_NativeImage_Create](#oh_nativeimage_create) (uint32_t textureId, uint32_t textureTarget) | Creates an **OH_NativeImage** instance to be associated with the OpenGL ES texture ID and target.<br>This function must be used in pair with [OH_NativeImage_Destroy](#oh_nativeimage_destroy). Otherwise, memory leak occurs.<br>This function is not thread-safe.| 52| [OHNativeWindow](_native_window.md#ohnativewindow) \* [OH_NativeImage_AcquireNativeWindow](#oh_nativeimage_acquirenativewindow) ([OH_NativeImage](#oh_nativeimage-1) \*image) | Obtains an **OHNativeWindow** instance associated with an **OH_NativeImage** instance.<br>This function is not thread-safe.<br>When **OH_NativeImage** is being destructed, the corresponding **OHNativeWindow** instance is released. If the **OHNativeWindow** pointer is obtained by using this function, set the pointer to null when releasing the **OH_NativeImage** instance, so as to prevent subsequent wild pointers.| 53| int32_t [OH_NativeImage_AttachContext](#oh_nativeimage_attachcontext) ([OH_NativeImage](#oh_nativeimage-1) \*image, uint32_t textureId) | Attaches an **OH_NativeImage** instance to the current OpenGL ES context. The OpenGL ES texture will be bound to an **GL_TEXTURE_EXTERNAL_OES** instance and updated through the **OH_NativeImage** instance.<br>This function is not thread-safe.| 54| int32_t [OH_NativeImage_DetachContext](#oh_nativeimage_detachcontext) ([OH_NativeImage](#oh_nativeimage-1) \*image) | Detaches an **OH_NativeImage** instance from the current OpenGL ES context.<br>This function is not thread-safe.| 55| int32_t [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage) ([OH_NativeImage](#oh_nativeimage-1) \*image) | Updates the OpenGL ES texture associated with the latest frame through an **OH_NativeImage** instance.<br>This function must be called in a thread of the OpenGL ES context.<br>This function must be called after the [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) callback is triggered.<br>This function is not thread-safe.| 56| int64_t [OH_NativeImage_GetTimestamp](#oh_nativeimage_gettimestamp) ([OH_NativeImage](#oh_nativeimage-1) \*image) | Obtains the timestamp of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.<br>This function is not thread-safe.| 57| int32_t [OH_NativeImage_GetTransformMatrix](#oh_nativeimage_gettransformmatrix) ([OH_NativeImage](#oh_nativeimage-1) \*image, float matrix[16]) | Obtains the transformation matrix of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.| 58| int32_t [OH_NativeImage_GetSurfaceId](#oh_nativeimage_getsurfaceid) ([OH_NativeImage](#oh_nativeimage-1) \*image, uint64_t \*surfaceId) | Obtains the surface ID of an **OH_NativeImage** instance.<br>This function is not thread-safe.| 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) | Registers a listener to listen for frame availability events.<br>Do not call other functions of this module in the callback.<br>This function is not thread-safe.| 60| int32_t [OH_NativeImage_UnsetOnFrameAvailableListener](#oh_nativeimage_unsetonframeavailablelistener) ([OH_NativeImage](#oh_nativeimage-1) \*image) | Deregisters the listener used to listen for frame availability events.<br>This function is not thread-safe.| 61| void [OH_NativeImage_Destroy](#oh_nativeimage_destroy) ([OH_NativeImage](#oh_nativeimage-1) \*\*image) | Destroys an **OH_NativeImage** instance created by calling **OH_NativeImage_Create**. After the instance is destroyed,<br>the pointer to the **OH_NativeImage** instance is assigned **NULL**.<br>This function is not thread-safe.| 62| int32_t [OH_NativeImage_GetTransformMatrixV2](#oh_nativeimage_gettransformmatrixv2) ([OH_NativeImage](#oh_nativeimage-1) \*image, float matrix[16]) | Obtains, based on the rotation angle set by the producer, the transform matrix of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.<br>The matrix is updated only after [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage) is called.<br>This function is not thread-safe.| 63| int32_t [OH_NativeImage_GetBufferMatrix](#oh_nativeimage_getbuffermatrix) ([OH_NativeImage](#oh_nativeimage-1) \*image, float matrix[16]) | Obtains the transformation matrix calculated based on the rotation angle set by the producer and the actual valid content area of the buffer.| 64| int32_t [OH_NativeImage_AcquireNativeWindowBuffer](#oh_nativeimage_acquirenativewindowbuffer) ([OH_NativeImage](#oh_nativeimage-1) \*image, [OHNativeWindowBuffer](_native_window.md#ohnativewindowbuffer) \*\*nativeWindowBuffer, int \*fenceFd) | Obtains an **OHNativeWindowBuffer** instance through an **OH_NativeImage** instance on the consumer side.<br>This function cannot be used together with [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage).<br>This function creates an **OHNativeWindowBuffer**.<br>When using the **OHNativeWindowBuffer**, call [OH_NativeWindow_NativeObjectReference](_native_window.md#oh_nativewindow_nativeobjectreference) to increase its reference count by one.<br>When finishing using the **OHNativeWindowBuffer**, call [OH_NativeWindow_NativeObjectUnreference](_native_window.md#oh_nativewindow_nativeobjectunreference) to decrease the reference count by one.<br>This function must be used in pair with [OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer). Otherwise, memory leak occurs.<br>When **fenceFd** is used up, you must close it.<br>This function is not thread-safe.| 65| int32_t [OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer) ([OH_NativeImage](#oh_nativeimage-1) \*image, [OHNativeWindowBuffer](_native_window.md#ohnativewindowbuffer) \*nativeWindowBuffer, int fenceFd) | Releases an **OHNativeWindowBuffer** instance through an **OH_NativeImage** instance.<br>The system will close **fenFd**. You do not need to close it.<br>This function is not thread-safe.| 66| [OH_NativeImage](#oh_nativeimage-1) \* [OH_ConsumerSurface_Create](#oh_consumersurface_create) () | Creates an **OH_NativeImage** instance as the consumer of the surface.<br>This function is used only for memory cycling of the surface consumer. Memory rendering is not proactively performed in the created **OH_NativeImage** instance.<br>This function cannot be used together with [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage).<br>This function must be used in pair with **OH_NativeImage_AcquireNativeWindowBuffer** and **OH_NativeImage_ReleaseNativeWindowBuffer**.<br>This function must be used in pair with [OH_NativeImage_Destroy](#oh_nativeimage_destroy). Otherwise, memory leak occurs.<br>This function is not thread-safe.| 67| int32_t [OH_ConsumerSurface_SetDefaultUsage](#oh_consumersurface_setdefaultusage) ([OH_NativeImage](#oh_nativeimage-1) \*image, uint64_t usage) | Sets the default read/write mode. This function is not thread-safe.| 68| int32_t [OH_ConsumerSurface_SetDefaultSize](#oh_consumersurface_setdefaultsize) ([OH_NativeImage](#oh_nativeimage-1) \*image, int32_t width, int32_t height) | Sets the default size of a geometric shape. This function is not thread-safe.| 69 70## Type Description 71 72 73### OH_NativeImage 74 75``` 76typedef struct OH_NativeImage OH_NativeImage 77``` 78 79**Description** 80 81Provides the declaration of an **OH_NativeImage** struct. 82 83**Since**: 9 84 85 86### OH_OnFrameAvailable 87 88``` 89typedef void(* OH_OnFrameAvailable) (void *context) 90``` 91 92**Description** 93 94Defines the callback function triggered when a frame is available. 95 96**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 97 98**Since**: 11 99 100**Parameters** 101 102| Name| Description| 103| -------- | -------- | 104| context | User-defined context information, which is returned when the callback is triggered.| 105 106 107### OH_OnFrameAvailableListener 108 109``` 110typedef struct OH_OnFrameAvailableListener OH_OnFrameAvailableListener 111``` 112 113**Description** 114 115Defines an **OH_NativeImage** listener, which is registered through [OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener). The listener triggers a callback when a frame is available. 116 117**Since**: 11 118 119 120### OHNativeErrorCode 121 122``` 123typedef enum OHNativeErrorCode OHNativeErrorCode 124``` 125**Description** 126 127Defines an enum for the error codes. 128 129**Since**: 12 130 131 132### OHNativeWindow 133 134``` 135typedef struct NativeWindow OHNativeWindow 136``` 137 138**Description** 139 140Provides the capability of accessing the **NativeWindow**. 141 142**Since**: 9 143 144### OHNativeWindowBuffer 145 146``` 147typedef struct NativeWindowBuffer OHNativeWindowBuffer 148``` 149 150**Description** 151 152Provides the declaration of a **NativeWindowBuffer** struct. 153 154**Since**: 12 155 156 157## Enum Description 158 159 160### OHNativeErrorCode 161 162``` 163enum OHNativeErrorCode 164``` 165**Description** 166 167Enumerates the error codes. 168 169**Since**: 12 170 171| Value| Description| 172| -------- | -------- | 173| NATIVE_ERROR_OK | The operation is successful. | 174| NATIVE_ERROR_MEM_OPERATION_ERROR<sup>15+</sup> | An error occurs during memory manipulation.| 175| NATIVE_ERROR_INVALID_ARGUMENTS | An input parameter is invalid. | 176| NATIVE_ERROR_NO_PERMISSION | You do not have the permission to perform the operation. | 177| NATIVE_ERROR_NO_BUFFER | No buffer is available. | 178| NATIVE_ERROR_NO_CONSUMER | The consumer does not exist. | 179| NATIVE_ERROR_NOT_INIT | Not initialized. | 180| NATIVE_ERROR_CONSUMER_CONNECTED | The consumer is connected. | 181| NATIVE_ERROR_BUFFER_STATE_INVALID | The buffer status does not meet the expectation. | 182| NATIVE_ERROR_BUFFER_IN_CACHE | The buffer is already in the buffer queue. | 183| NATIVE_ERROR_BUFFER_QUEUE_FULL | The queue is full. | 184| NATIVE_ERROR_BUFFER_NOT_IN_CACHE | The buffer is not in the buffer queue. | 185| NATIVE_ERROR_CONSUMER_DISCONNECTED | The consumer is disconnected.| 186| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | No listener is registered on the consumer side.| 187| NATIVE_ERROR_UNSUPPORTED | The device or platform does not support the operation. | 188| NATIVE_ERROR_UNKNOWN | Unknown error. Check the log. | 189| NATIVE_ERROR_HDI_ERROR | Failed to call the HDI. | 190| NATIVE_ERROR_BINDER_ERROR | Cross-process communication failed. | 191| NATIVE_ERROR_EGL_STATE_UNKNOWN | The EGL environment is abnormal. | 192| NATIVE_ERROR_EGL_API_FAILED | Failed to call the EGL APIs. | 193 194 195## Function Description 196 197### OH_NativeImage_GetBufferMatrix() 198 199``` 200int32_t OH_NativeImage_GetBufferMatrix (OH_NativeImage* image, float matrix[16] ) 201``` 202 203**Description** 204 205Obtains the transformation matrix calculated based on the rotation angle set by the producer and the actual valid content area of the buffer. 206 207This function returns a transformation matrix that is determined by the buffer's rotation angle and actual valid content area during the consumption of the buffer by [OH_NativeImage](#oh_nativeimage-1), specifically when invoking the function [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage) or [OH_NativeImage_AcquireNativeWindowBuffer](#oh_nativeimage_acquirenativewindowbuffer). 208 209This function is not thread-safe. 210 211**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 212 213**Valid since**: 15 214 215**Parameters** 216 217| Name| Description| 218| -------- | -------- | 219| image | Pointer to an [OH_NativeImage](#oh_nativeimage-1) instance.| 220| matrix | Buffer used to store the 4 x 4 transformation matrix obtained.| 221 222**Returns** 223 224Returns **NATIVE_ERROR_OK** if the operation is successful. 225 226Returns **NATIVE_ERROR_INVALID_ARGUMENTS** (error code: 40001000) if **image** is a null pointer. 227 228Returns **NATIVE_ERROR_MEM_OPERATION_ERROR** (error code: 30001000) if the transformation matrix fails to be obtained due to a memory manipulation error. 229 230### OH_ConsumerSurface_SetDefaultUsage() 231 232``` 233int32_t OH_ConsumerSurface_SetDefaultUsage (OH_NativeImage* image, uint64_t usage ) 234``` 235 236**Description** 237 238Sets the default read/write mode. This function is not thread-safe. 239 240**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 241 242**Since**: 13 243 244**Parameters** 245 246| Name| Description| 247| -------- | -------- | 248| image | Pointer to an **OH_NativeImage** instance.| 249| usage | Read/write mode. For details about the available options, see **OH_NativeBuffer_Usage**.| 250 251**Returns** 252 253Returns **NATIVE_ERROR_OK** if the operation is successful. 254 255Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image** is a null pointer. 256 257 258### OH_ConsumerSurface_SetDefaultSize() 259 260``` 261int32_t OH_ConsumerSurface_SetDefaultSize (OH_NativeImage* image, int32_t width, int32_t height ) 262``` 263 264**Description** 265 266Sets the default size of a geometric shape. This function is not thread-safe. 267 268**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 269 270**Since**: 13 271 272**Parameters** 273 274| Name| Description| 275| -------- | -------- | 276| image | Pointer to an **OH_NativeImage** instance.| 277| width | Width of the geometric shape. The value is greater than 0, in pixels.| 278| height | Height of the geometric shape. The value is greater than 0, in pixels.| 279 280**Returns** 281 282Returns **NATIVE_ERROR_OK** if the operation is successful. 283 284Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image** is a null pointer or **width** or **height** is less than 0. 285 286### OH_ConsumerSurface_Create() 287 288``` 289OH_NativeImage* OH_ConsumerSurface_Create () 290``` 291 292**Description** 293 294Creates an **OH_NativeImage** instance as the consumer of the surface. 295 296This function is used only for memory cycling of the surface consumer. Memory rendering is not proactively performed in the created **OH_NativeImage** instance. 297 298This function cannot be used together with [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage). 299 300This function must be used in pair with **OH_NativeImage_AcquireNativeWindowBuffer** and **OH_NativeImage_ReleaseNativeWindowBuffer**. 301 302This function must be used in pair with [OH_NativeImage_Destroy](#oh_nativeimage_destroy). Otherwise, memory leak occurs. 303 304This function is not thread-safe. 305 306**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 307 308**Since**: 12 309 310**Returns** 311 312Returns a pointer to the **OH_NativeImage** instance if the operation is successful; returns **NULL** otherwise. 313 314 315### OH_NativeImage_AcquireNativeWindowBuffer() 316 317``` 318int32_t OH_NativeImage_AcquireNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd ) 319``` 320 321**Description** 322 323Obtains an **OHNativeWindowBuffer** instance through an **OH_NativeImage** instance on the consumer side. 324 325This function cannot be used together with [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage). 326 327This function creates an **OHNativeWindowBuffer**. 328 329When using the **OHNativeWindowBuffer**, call **OH_NativeWindow_NativeObjectReference** to increase its reference count by one. 330 331When finishing using the **OHNativeWindowBuffer**, call **OH_NativeWindow_NativeObjectUnreference** to decrease the reference count by one. 332 333This function must be used in pair with [OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer). Otherwise, memory leak occurs. 334 335When **fenceFd** is used up, you must close it. 336 337This function is not thread-safe. 338 339**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 340 341**Since**: 12 342 343**Parameters** 344 345| Name| Description| 346| -------- | -------- | 347| image | Pointer to an **OH_NativeImage** instance.| 348| nativeWindowBuffer | Double pointer to the **OHNativeWindowBuffer** instance obtained.| 349| fenceFd | Pointer to the file descriptor handle.| 350 351**Returns** 352 353Returns **NATIVE_ERROR_OK** if the operation is successful. 354 355Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image**, **nativeWindowBuffer**, or **fenceFd** is a null pointer. 356 357Returns **NATIVE_ERROR_NO_BUFFER** if no buffer is available for consumption. 358 359 360### OH_NativeImage_ReleaseNativeWindowBuffer() 361 362``` 363int32_t OH_NativeImage_ReleaseNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd ) 364``` 365 366**Description** 367 368Releases an **OHNativeWindowBuffer** instance through an **OH_NativeImage** instance. 369 370The system will close **fenFd**. You do not need to close it. 371 372This function is not thread-safe. 373 374**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 375 376**Since**: 12 377 378**Parameters** 379 380| Name| Description| 381| -------- | -------- | 382| image | Pointer to an **OH_NativeImage** instance.| 383| nativeWindowBuffer | Pointer to an **OHNativeWindowBuffer** instance.| 384| fenceFd | File descriptor handle, which is used for concurrent synchronization control.| 385 386**Returns** 387 388Returns **NATIVE_ERROR_OK** if the operation is successful. 389 390Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image** or **nativeWindowBuffer** is a null pointer. 391 392Returns **NATIVE_ERROR_BUFFER_STATE_INVALID** if the status of **nativeWindowBuffer** is invalid. 393 394Returns **NATIVE_ERROR_BUFFER_NOT_IN_CACHE** if **nativeWindowBuffer** is not in the cache. 395 396 397 398### OH_NativeImage_AcquireNativeWindow() 399 400``` 401OHNativeWindow* OH_NativeImage_AcquireNativeWindow (OH_NativeImage * image) 402``` 403 404**Description** 405 406Obtains an **OHNativeWindow** instance associated with an **OH_NativeImage** instance. 407 408This function is not thread-safe. 409 410When **OH_NativeImage** is being destructed, the corresponding **OHNativeWindow** instance is released. If the **OHNativeWindow** pointer is obtained by using this function, set the pointer to null when releasing the **OH_NativeImage** instance, so as to prevent subsequent wild pointers. 411 412**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 413 414**Since**: 9 415 416**Parameters** 417 418| Name| Description| 419| -------- | -------- | 420| image | Pointer to an **OH_NativeImage** instance.| 421 422**Returns** 423 424Returns a pointer to the **OHNativeWindow** instance if the operation is successful; returns **NULL** otherwise. 425 426 427### OH_NativeImage_AttachContext() 428 429``` 430int32_t OH_NativeImage_AttachContext (OH_NativeImage * image, uint32_t textureId ) 431``` 432 433**Description** 434 435Attaches an **OH_NativeImage** instance to the current OpenGL ES context. 436 437The OpenGL ES texture will be bound to an **GL_TEXTURE_EXTERNAL_OES** instance and updated through the **OH_NativeImage** instance. 438 439This function is not thread-safe. 440 441**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 442 443**Since**: 9 444 445**Parameters** 446 447| Name| Description| 448| -------- | -------- | 449| image | Pointer to an **OH_NativeImage** instance.| 450| textureId | ID of the OpenGL ES texture to which the **OH_NativeImage** instance is to be attached.| 451 452**Returns** 453 454Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 455 456 457### OH_NativeImage_Create() 458 459``` 460OH_NativeImage* OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget ) 461``` 462 463**Description** 464 465Creates an **OH_NativeImage** instance to be associated with the OpenGL ES texture ID and target. 466 467This function must be used in pair with **OH_NativeImage_Destroy**. Otherwise, memory leak occurs. 468 469This function is not thread-safe. 470 471**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 472 473**Since**: 9 474 475**Parameters** 476 477| Name| Description| 478| -------- | -------- | 479| textureId | OpenGL ES texture ID.| 480| textureTarget | OpenGL ES texture target.| 481 482**Returns** 483 484Returns a pointer to the **OH_NativeImage** instance if the operation is successful; returns **NULL** otherwise. 485 486 487### OH_NativeImage_Destroy() 488 489``` 490void OH_NativeImage_Destroy (OH_NativeImage ** image) 491``` 492 493**Description** 494 495Destroys an **OH_NativeImage** instance created by calling **OH_NativeImage_Create**. After the instance is destroyed, 496 497the pointer to the **OH_NativeImage** instance is assigned **NULL**. 498 499This function is not thread-safe. 500 501**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 502 503**Since**: 9 504 505**Parameters** 506 507| Name| Description| 508| -------- | -------- | 509| image | Pointer to an **OH_NativeImage** instance.| 510 511 512### OH_NativeImage_DetachContext() 513 514``` 515int32_t OH_NativeImage_DetachContext (OH_NativeImage * image) 516``` 517 518**Description** 519 520Detaches an **OH_NativeImage** instance from the current OpenGL ES context. 521 522This function is not thread-safe. 523 524**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 525 526**Since**: 9 527 528**Parameters** 529 530| Name| Description| 531| -------- | -------- | 532| image | Pointer to an **OH_NativeImage** instance.| 533 534**Returns** 535 536Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 537 538 539### OH_NativeImage_GetSurfaceId() 540 541``` 542int32_t OH_NativeImage_GetSurfaceId (OH_NativeImage * image, uint64_t * surfaceId ) 543``` 544 545**Description** 546 547Obtains the surface ID of an **OH_NativeImage** instance. 548 549This function is not thread-safe. 550 551**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 552 553**Since**: 11 554 555**Parameters** 556 557| Name| Description| 558| -------- | -------- | 559| image | Pointer to an **OH_NativeImage** instance.| 560| surfaceId | Pointer to the surface ID.| 561 562**Returns** 563 564Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 565 566 567### OH_NativeImage_GetTimestamp() 568 569``` 570int64_t OH_NativeImage_GetTimestamp (OH_NativeImage * image) 571``` 572 573**Description** 574 575Obtains the timestamp of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function. 576 577This function is not thread-safe. 578 579**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 580 581**Since**: 9 582 583**Parameters** 584 585| Name| Description| 586| -------- | -------- | 587| image | Pointer to an **OH_NativeImage** instance.| 588 589**Returns** 590 591Returns the timestamp of the texture image. 592 593 594### OH_NativeImage_GetTransformMatrix() 595 596``` 597int32_t OH_NativeImage_GetTransformMatrix (OH_NativeImage * image, float matrix[16] ) 598``` 599 600**Description** 601 602Obtains the transformation matrix of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function. 603 604**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 605 606**Deprecated from**: 12 607 608**Substitute**: [OH_NativeImage_GetTransformMatrixV2](#oh_nativeimage_gettransformmatrixv2) 609 610**Since**: 9 611 612**Parameters** 613 614| Name| Description| 615| -------- | -------- | 616| image | Pointer to an **OH_NativeImage** instance.| 617| matrix | Buffer used to store the 4 \* 4 transform matrix obtained.| 618 619**Returns** 620 621Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 622 623### OH_NativeImage_GetTransformMatrixV2() 624 625``` 626int32_t OH_NativeImage_GetTransformMatrixV2 (OH_NativeImage* image, float matrix[16] ) 627``` 628**Description** 629 630Obtains, based on the rotation angle set by the producer, the transform matrix of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function. 631 632The matrix is updated only after **OH_NativeImage_UpdateSurfaceImage** is called. 633 634This function is not thread-safe. 635 636**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 637 638**Since**: 12 639 640**Parameters** 641 642| Name| Description| 643| -------- | -------- | 644| image | Pointer to an **OH_NativeImage** instance. | 645| matrix | Buffer used to store the 4 \* 4 transform matrix obtained. | 646 647**Returns** 648 649Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 650 651### OH_NativeImage_SetOnFrameAvailableListener() 652 653``` 654int32_t OH_NativeImage_SetOnFrameAvailableListener (OH_NativeImage * image, OH_OnFrameAvailableListener listener ) 655``` 656 657**Description** 658 659Registers a listener to listen for frame availability events. 660 661Do not call other functions of this module in the callback. 662 663This function is not thread-safe. 664 665**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 666 667**Since**: 11 668 669**Parameters** 670 671| Name| Description| 672| -------- | -------- | 673| image | Pointer to an **OH_NativeImage** instance.| 674| listener | Listener to register.| 675 676**Returns** 677 678Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 679 680 681### OH_NativeImage_UnsetOnFrameAvailableListener() 682 683``` 684int32_t OH_NativeImage_UnsetOnFrameAvailableListener (OH_NativeImage * image) 685``` 686 687**Description** 688 689Deregisters the listener used to listen for frame availability events. 690 691This function is not thread-safe. 692 693**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 694 695**Since**: 11 696 697**Parameters** 698 699| Name| Description| 700| -------- | -------- | 701| image | Pointer to an **OH_NativeImage** instance.| 702 703**Returns** 704 705Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 706 707 708### OH_NativeImage_UpdateSurfaceImage() 709 710``` 711int32_t OH_NativeImage_UpdateSurfaceImage (OH_NativeImage * image) 712``` 713 714**Description** 715 716Updates the OpenGL ES texture associated with the latest frame through an **OH_NativeImage** instance. 717 718This function must be called in a thread of the OpenGL ES context. 719 720This function must be called after the **OH_OnFrameAvailableListener** callback is triggered. 721 722This function is not thread-safe. 723 724**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage 725 726**Since**: 9 727 728**Parameters** 729 730| Name| Description| 731| -------- | -------- | 732| image | Pointer to an **OH_NativeImage** instance.| 733 734**Returns** 735 736Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 737