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