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