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### OH_ConsumerSurface_SetDefaultUsage()
196
197```
198int32_t OH_ConsumerSurface_SetDefaultUsage (OH_NativeImage* image, uint64_t usage )
199```
200
201**Description**
202
203Sets the default read/write mode. This function is not thread-safe.
204
205**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
206
207**Since**: 13
208
209**Parameters**
210
211| Name| Description|
212| -------- | -------- |
213| image | Pointer to an **OH_NativeImage** instance.|
214| usage | Read/write mode. For details about the available options, see **OH_NativeBuffer_Usage**.|
215
216**Returns**
217
218Returns **NATIVE_ERROR_OK** if the operation is successful.
219
220Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image** is a null pointer.
221
222
223### OH_ConsumerSurface_SetDefaultSize()
224
225```
226int32_t OH_ConsumerSurface_SetDefaultSize (OH_NativeImage* image, int32_t width, int32_t height )
227```
228
229**Description**
230
231Sets the default size of a geometric shape. This function is not thread-safe.
232
233**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
234
235**Since**: 13
236
237**Parameters**
238
239| Name| Description|
240| -------- | -------- |
241| image | Pointer to an **OH_NativeImage** instance.|
242| width | Width of the geometric shape. The value is greater than 0, in pixels.|
243| height | Height of the geometric shape. The value is greater than 0, in pixels.|
244
245**Returns**
246
247Returns **NATIVE_ERROR_OK** if the operation is successful.
248
249Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image** is a null pointer or **width** or **height** is less than 0.
250
251### OH_ConsumerSurface_Create()
252
253```
254OH_NativeImage* OH_ConsumerSurface_Create ()
255```
256
257**Description**
258
259Creates an **OH_NativeImage** instance as the consumer of the surface.
260
261This function is used only for memory cycling of the surface consumer. Memory rendering is not proactively performed in the created **OH_NativeImage** instance.
262
263This function cannot be used together with [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage).
264
265This function must be used in pair with **OH_NativeImage_AcquireNativeWindowBuffer** and **OH_NativeImage_ReleaseNativeWindowBuffer**.
266
267This function must be used in pair with [OH_NativeImage_Destroy](#oh_nativeimage_destroy). Otherwise, memory leak occurs.
268
269This function is not thread-safe.
270
271**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
272
273**Since**: 12
274
275**Returns**
276
277Returns a pointer to the **OH_NativeImage** instance if the operation is successful; returns **NULL** otherwise.
278
279
280### OH_NativeImage_AcquireNativeWindowBuffer()
281
282```
283int32_t OH_NativeImage_AcquireNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd )
284```
285
286**Description**
287
288Obtains an **OHNativeWindowBuffer** instance through an **OH_NativeImage** instance on the consumer side.
289
290This function cannot be used together with [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage).
291
292This function creates an **OHNativeWindowBuffer**.
293
294When using the **OHNativeWindowBuffer**, call **OH_NativeWindow_NativeObjectReference** to increase its reference count by one.
295
296When finishing using the **OHNativeWindowBuffer**, call **OH_NativeWindow_NativeObjectUnreference** to decrease the reference count by one.
297
298This function must be used in pair with [OH_NativeImage_ReleaseNativeWindowBuffer](#oh_nativeimage_releasenativewindowbuffer). Otherwise, memory leak occurs.
299
300When **fenceFd** is used up, you must close it.
301
302This function is not thread-safe.
303
304**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
305
306**Since**: 12
307
308**Parameters**
309
310| Name| Description|
311| -------- | -------- |
312| image | Pointer to an **OH_NativeImage** instance.|
313| nativeWindowBuffer | Double pointer to the **OHNativeWindowBuffer** instance obtained.|
314| fenceFd | Pointer to the file descriptor handle.|
315
316**Returns**
317
318Returns **NATIVE_ERROR_OK** if the operation is successful.
319
320Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image**, **nativeWindowBuffer**, or **fenceFd** is a null pointer.
321
322Returns **NATIVE_ERROR_NO_BUFFER** if no buffer is available for consumption.
323
324
325### OH_NativeImage_ReleaseNativeWindowBuffer()
326
327```
328int32_t OH_NativeImage_ReleaseNativeWindowBuffer (OH_NativeImage* image, OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd )
329```
330
331**Description**
332
333Releases an **OHNativeWindowBuffer** instance through an **OH_NativeImage** instance.
334
335The system will close **fenFd**. You do not need to 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 | Pointer to an **OHNativeWindowBuffer** instance.|
349| fenceFd | File descriptor handle, which is used for concurrent synchronization control.|
350
351**Returns**
352
353Returns **NATIVE_ERROR_OK** if the operation is successful.
354
355Returns **NATIVE_ERROR_INVALID_ARGUMENTS** if **image** or **nativeWindowBuffer** is a null pointer.
356
357Returns **NATIVE_ERROR_BUFFER_STATE_INVALID** if the status of **nativeWindowBuffer** is invalid.
358
359Returns **NATIVE_ERROR_BUFFER_NOT_IN_CACHE** if **nativeWindowBuffer** is not in the cache.
360
361
362
363### OH_NativeImage_AcquireNativeWindow()
364
365```
366OHNativeWindow* OH_NativeImage_AcquireNativeWindow (OH_NativeImage * image)
367```
368
369**Description**
370
371Obtains an **OHNativeWindow** instance associated with an **OH_NativeImage** instance.
372
373This function is not thread-safe.
374
375When **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.
376
377**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
378
379**Since**: 9
380
381**Parameters**
382
383| Name| Description|
384| -------- | -------- |
385| image | Pointer to an **OH_NativeImage** instance.|
386
387**Returns**
388
389Returns a pointer to the **OHNativeWindow** instance if the operation is successful; returns **NULL** otherwise.
390
391
392### OH_NativeImage_AttachContext()
393
394```
395int32_t OH_NativeImage_AttachContext (OH_NativeImage * image, uint32_t textureId )
396```
397
398**Description**
399
400Attaches an **OH_NativeImage** instance to the current OpenGL ES context.
401
402The OpenGL ES texture will be bound to an **GL_TEXTURE_EXTERNAL_OES** instance and updated through the **OH_NativeImage** instance.
403
404This function is not thread-safe.
405
406**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
407
408**Since**: 9
409
410**Parameters**
411
412| Name| Description|
413| -------- | -------- |
414| image | Pointer to an **OH_NativeImage** instance.|
415| textureId | ID of the OpenGL ES texture to which the **OH_NativeImage** instance is to be attached.|
416
417**Returns**
418
419Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
420
421
422### OH_NativeImage_Create()
423
424```
425OH_NativeImage* OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget )
426```
427
428**Description**
429
430Creates an **OH_NativeImage** instance to be associated with the OpenGL ES texture ID and target.
431
432This function must be used in pair with **OH_NativeImage_Destroy**. Otherwise, memory leak occurs.
433
434This function is not thread-safe.
435
436**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
437
438**Since**: 9
439
440**Parameters**
441
442| Name| Description|
443| -------- | -------- |
444| textureId | OpenGL ES texture ID.|
445| textureTarget | OpenGL ES texture target.|
446
447**Returns**
448
449Returns a pointer to the **OH_NativeImage** instance if the operation is successful; returns **NULL** otherwise.
450
451
452### OH_NativeImage_Destroy()
453
454```
455void OH_NativeImage_Destroy (OH_NativeImage ** image)
456```
457
458**Description**
459
460Destroys an **OH_NativeImage** instance created by calling **OH_NativeImage_Create**. After the instance is destroyed,
461
462the pointer to the **OH_NativeImage** instance is assigned **NULL**.
463
464This function is not thread-safe.
465
466**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
467
468**Since**: 9
469
470**Parameters**
471
472| Name| Description|
473| -------- | -------- |
474| image | Pointer to an **OH_NativeImage** instance.|
475
476
477### OH_NativeImage_DetachContext()
478
479```
480int32_t OH_NativeImage_DetachContext (OH_NativeImage * image)
481```
482
483**Description**
484
485Detaches an **OH_NativeImage** instance from the current OpenGL ES context.
486
487This function is not thread-safe.
488
489**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
490
491**Since**: 9
492
493**Parameters**
494
495| Name| Description|
496| -------- | -------- |
497| image | Pointer to an **OH_NativeImage** instance.|
498
499**Returns**
500
501Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
502
503
504### OH_NativeImage_GetSurfaceId()
505
506```
507int32_t OH_NativeImage_GetSurfaceId (OH_NativeImage * image, uint64_t * surfaceId )
508```
509
510**Description**
511
512Obtains the surface ID of an **OH_NativeImage** instance.
513
514This function is not thread-safe.
515
516**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
517
518**Since**: 11
519
520**Parameters**
521
522| Name| Description|
523| -------- | -------- |
524| image | Pointer to an **OH_NativeImage** instance.|
525| surfaceId | Pointer to the surface ID.|
526
527**Returns**
528
529Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
530
531
532### OH_NativeImage_GetTimestamp()
533
534```
535int64_t OH_NativeImage_GetTimestamp (OH_NativeImage * image)
536```
537
538**Description**
539
540Obtains the timestamp of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.
541
542This function is not thread-safe.
543
544**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
545
546**Since**: 9
547
548**Parameters**
549
550| Name| Description|
551| -------- | -------- |
552| image | Pointer to an **OH_NativeImage** instance.|
553
554**Returns**
555
556Returns the timestamp of the texture image.
557
558
559### OH_NativeImage_GetTransformMatrix()
560
561```
562int32_t OH_NativeImage_GetTransformMatrix (OH_NativeImage * image, float matrix[16] )
563```
564
565**Description**
566
567Obtains the transformation matrix of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.
568
569**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
570
571**Deprecated from**: 12
572
573**Substitute**: [OH_NativeImage_GetTransformMatrixV2](#oh_nativeimage_gettransformmatrixv2)
574
575**Since**: 9
576
577**Parameters**
578
579| Name| Description|
580| -------- | -------- |
581| image | Pointer to an **OH_NativeImage** instance.|
582| matrix | Buffer used to store the 4 \* 4 transform matrix obtained.|
583
584**Returns**
585
586Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
587
588### OH_NativeImage_GetTransformMatrixV2()
589
590```
591int32_t OH_NativeImage_GetTransformMatrixV2 (OH_NativeImage* image, float matrix[16] )
592```
593**Description**
594
595Obtains, based on the rotation angle set by the producer, the transform matrix of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.
596
597The matrix is updated only after **OH_NativeImage_UpdateSurfaceImage** is called.
598
599This function is not thread-safe.
600
601**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
602
603**Since**: 12
604
605**Parameters**
606
607| Name| Description|
608| -------- | -------- |
609| image | Pointer to an **OH_NativeImage** instance. |
610| matrix | Buffer used to store the 4 \* 4 transform matrix obtained. |
611
612**Returns**
613
614Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
615
616### OH_NativeImage_SetOnFrameAvailableListener()
617
618```
619int32_t OH_NativeImage_SetOnFrameAvailableListener (OH_NativeImage * image, OH_OnFrameAvailableListener listener )
620```
621
622**Description**
623
624Registers a listener to listen for frame availability events.
625
626Do not call other functions of this module in the callback.
627
628This function is not thread-safe.
629
630**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
631
632**Since**: 11
633
634**Parameters**
635
636| Name| Description|
637| -------- | -------- |
638| image | Pointer to an **OH_NativeImage** instance.|
639| listener | Listener to register.|
640
641**Returns**
642
643Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
644
645
646### OH_NativeImage_UnsetOnFrameAvailableListener()
647
648```
649int32_t OH_NativeImage_UnsetOnFrameAvailableListener (OH_NativeImage * image)
650```
651
652**Description**
653
654Deregisters the listener used to listen for frame availability events.
655
656This function is not thread-safe.
657
658**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
659
660**Since**: 11
661
662**Parameters**
663
664| Name| Description|
665| -------- | -------- |
666| image | Pointer to an **OH_NativeImage** instance.|
667
668**Returns**
669
670Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
671
672
673### OH_NativeImage_UpdateSurfaceImage()
674
675```
676int32_t OH_NativeImage_UpdateSurfaceImage (OH_NativeImage * image)
677```
678
679**Description**
680
681Updates the OpenGL ES texture associated with the latest frame through an **OH_NativeImage** instance.
682
683This function must be called in a thread of the OpenGL ES context.
684
685This function must be called after the **OH_OnFrameAvailableListener** callback is triggered.
686
687This function is not thread-safe.
688
689**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
690
691**Since**: 9
692
693**Parameters**
694
695| Name| Description|
696| -------- | -------- |
697| image | Pointer to an **OH_NativeImage** instance.|
698
699**Returns**
700
701Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise.
702