• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# OH_NativeImage
2
3
4## Overview
5
6Provides 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| [OH_NativeImage](#oh_nativeimage) | Provides the declaration of an **OH_NativeImage** struct.|
35| [OHNativeWindow](#ohnativewindow) | typedef struct NativeWindow<br>Provides the declaration of a **NativeWindow** struct.|
36| [OH_OnFrameAvailable](#oh_onframeavailable) | Defines the callback function triggered when a frame is available.|
37| [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.|
38
39
40### Functions
41
42| Name| Description|
43| -------- | -------- |
44| [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.|
45| [OH_NativeImage_AcquireNativeWindow](#oh_nativeimage_acquirenativewindow) ([OH_NativeImage](#oh_nativeimage) \*image) | Obtains an **OHNativeWindow** instance associated with an **OH_NativeImage** instance. You need to call **OH_NativeWindow_DestroyNativeWindow** to release the **OHNativeWindow** instance when it is no longer required.<br>* |
46| [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.<br>The OpenGL ES texture will be bound to an **GL_TEXTURE_EXTERNAL_OES** instance and updated through the **OH_NativeImage** instance.|
47| [OH_NativeImage_DetachContext](#oh_nativeimage_detachcontext) ([OH_NativeImage](#oh_nativeimage) \*image) | Detaches an **OH_NativeImage** instance from the current OpenGL ES context.|
48| [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.|
49| [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.|
50| [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.|
51| [OH_NativeImage_GetSurfaceId](#oh_nativeimage_getsurfaceid) ([OH_NativeImage](#oh_nativeimage) \*image, uint64_t \*surfaceId) | Obtains the surface ID of an **OH_NativeImage** instance.|
52| [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.|
53| [OH_NativeImage_UnsetOnFrameAvailableListener](#oh_nativeimage_unsetonframeavailablelistener) ([OH_NativeImage](#oh_nativeimage) \*image) | Deregisters the listener used to listen for frame availability events.|
54| [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, the pointer to the **OH_NativeImage** instance is assigned **NULL**.|
55
56
57## Type Description
58
59
60### OH_NativeImage
61
62```
63typedef struct OH_NativeImageOH_NativeImage
64```
65
66**Description**
67
68Provides the declaration of an **OH_NativeImage** struct.
69
70**Since**: 9
71
72
73### OH_OnFrameAvailable
74
75```
76typedef void(* OH_OnFrameAvailable) (void *context)
77```
78
79**Description**
80
81Defines the callback function triggered when a frame is available.
82
83**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
84
85**Since**: 11
86
87**Parameters**
88
89| Name| Description|
90| -------- | -------- |
91| context | User-defined context information, which is returned when the callback is triggered.|
92
93
94### OH_OnFrameAvailableListener
95
96```
97typedef struct OH_OnFrameAvailableListener OH_OnFrameAvailableListener
98```
99
100**Description**
101
102Defines an **OH_NativeImage** listener, which is registered through [OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener). The listener triggers a callback when a frame is available.
103
104**Since**: 11
105
106
107### OHNativeWindow
108
109```
110typedef struct NativeWindow OHNativeWindow
111```
112
113**Description**
114
115Provides the capability of accessing the **NativeWindow**.
116
117**Since**: 9
118
119
120## Function Description
121
122
123### OH_NativeImage_AcquireNativeWindow()
124
125```
126OHNativeWindow* OH_NativeImage_AcquireNativeWindow (OH_NativeImage * image)
127```
128
129**Description**
130
131Obtains an **OHNativeWindow** instance associated with an **OH_NativeImage** instance. You need to call **OH_NativeWindow_DestroyNativeWindow** to release the **OHNativeWindow** instance when it is no longer required.
132
133*
134
135**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
136
137**Since**: 9
138
139**Parameters**
140
141| Name| Description|
142| -------- | -------- |
143| image | Pointer to an **OH_NativeImage** instance.|
144
145**Returns**
146
147Returns a pointer to the **OHNativeWindow** instance if the operation is successful; returns **NULL** otherwise.
148
149
150### OH_NativeImage_AttachContext()
151
152```
153int32_t OH_NativeImage_AttachContext (OH_NativeImage * image, uint32_t textureId )
154```
155
156**Description**
157
158Attaches an **OH_NativeImage** instance to the current OpenGL ES context.
159
160The OpenGL ES texture will be bound to an **GL_TEXTURE_EXTERNAL_OES** instance and updated through the **OH_NativeImage** instance.
161
162**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
163
164**Since**: 9
165
166**Parameters**
167
168| Name| Description|
169| -------- | -------- |
170| image | Pointer to an **OH_NativeImage** instance.|
171| textureId | ID of the OpenGL ES texture to which the **OH_NativeImage** instance is to be attached.|
172
173**Returns**
174
175Returns **0** if the operation is successful.
176
177
178### OH_NativeImage_Create()
179
180```
181OH_NativeImage* OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget )
182```
183
184**Description**
185
186Creates an **OH_NativeImage** instance to be associated with the OpenGL ES texture ID and target.
187
188**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
189
190**Since**: 9
191
192**Parameters**
193
194| Name| Description|
195| -------- | -------- |
196| textureId | OpenGL ES texture ID.|
197| textureTarget | OpenGL ES texture target.|
198
199**Returns**
200
201Returns a pointer to the **OH_NativeImage** instance if the operation is successful; returns **NULL** otherwise.
202
203
204### OH_NativeImage_Destroy()
205
206```
207void OH_NativeImage_Destroy (OH_NativeImage ** image)
208```
209
210**Description**
211
212Destroys an **OH_NativeImage** instance created by calling **OH_NativeImage_Create**. After the instance is destroyed,
213
214the pointer to the **OH_NativeImage** instance is assigned **NULL**.
215
216**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
217
218**Since**: 9
219
220**Parameters**
221
222| Name| Description|
223| -------- | -------- |
224| image | Pointer to an **OH_NativeImage** instance.|
225
226
227### OH_NativeImage_DetachContext()
228
229```
230int32_t OH_NativeImage_DetachContext (OH_NativeImage * image)
231```
232
233**Description**
234
235Detaches an **OH_NativeImage** instance from the current OpenGL ES context.
236
237**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
238
239**Since**: 9
240
241**Parameters**
242
243| Name| Description|
244| -------- | -------- |
245| image | Pointer to an **OH_NativeImage** instance.|
246
247**Returns**
248
249Returns **0** if the operation is successful.
250
251
252### OH_NativeImage_GetSurfaceId()
253
254```
255int32_t OH_NativeImage_GetSurfaceId (OH_NativeImage * image, uint64_t * surfaceId )
256```
257
258**Description**
259
260Obtains the surface ID of an **OH_NativeImage** instance.
261
262**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
263
264**Since**: 11
265
266**Parameters**
267
268| Name| Description|
269| -------- | -------- |
270| image | Pointer to an **OH_NativeImage** instance.|
271| surfaceId | Pointer to the surface ID.|
272
273**Returns**
274
275Returns **0** if the operation is successful.
276
277
278### OH_NativeImage_GetTimestamp()
279
280```
281int64_t OH_NativeImage_GetTimestamp (OH_NativeImage * image)
282```
283
284**Description**
285
286Obtains the timestamp of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.
287
288**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
289
290**Since**: 9
291
292**Parameters**
293
294| Name| Description|
295| -------- | -------- |
296| image | Pointer to an **OH_NativeImage** instance.|
297
298**Returns**
299
300Returns the timestamp of the texture image.
301
302
303### OH_NativeImage_GetTransformMatrix()
304
305```
306int32_t OH_NativeImage_GetTransformMatrix (OH_NativeImage * image, float matrix[16] )
307```
308
309**Description**
310
311Obtains the transformation matrix of the texture image that recently called the **OH_NativeImage_UpdateSurfaceImage** function.
312
313**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
314
315**Since**: 9
316
317**Parameters**
318
319| Name| Description|
320| -------- | -------- |
321| image | Pointer to an **OH_NativeImage** instance.|
322| matrix | Buffer used to store the 4 \* 4 transform matrix obtained.|
323
324**Returns**
325
326Returns **0** if the operation is successful.
327
328
329### OH_NativeImage_SetOnFrameAvailableListener()
330
331```
332int32_t OH_NativeImage_SetOnFrameAvailableListener (OH_NativeImage * image, OH_OnFrameAvailableListener listener )
333```
334
335**Description**
336
337Registers a listener to listen for frame availability events.
338
339**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
340
341**Since**: 11
342
343**Parameters**
344
345| Name| Description|
346| -------- | -------- |
347| image | Pointer to an **OH_NativeImage** instance.|
348| listener | Listener to register.|
349
350**Returns**
351
352Returns **0** if the operation is successful.
353
354
355### OH_NativeImage_UnsetOnFrameAvailableListener()
356
357```
358int32_t OH_NativeImage_UnsetOnFrameAvailableListener (OH_NativeImage * image)
359```
360
361**Description**
362
363Deregisters the listener used to listen for frame availability events.
364
365**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
366
367**Since**: 11
368
369**Parameters**
370
371| Name| Description|
372| -------- | -------- |
373| image | Pointer to an **OH_NativeImage** instance.|
374
375**Returns**
376
377Returns **0** if the operation is successful.
378
379
380### OH_NativeImage_UpdateSurfaceImage()
381
382```
383int32_t OH_NativeImage_UpdateSurfaceImage (OH_NativeImage * image)
384```
385
386**Description**
387
388Updates the OpenGL ES texture associated with the latest frame through an **OH_NativeImage** instance.
389
390**System capability**: SystemCapability.Graphic.Graphic2D.NativeImage
391
392**Since**: 9
393
394**Parameters**
395
396| Name| Description|
397| -------- | -------- |
398| image | Pointer to an **OH_NativeImage** instance.|
399
400**Returns**
401
402Returns **0** if the operation is successful.
403