1# OH_NativeImage 2 3 4## 概述 5 6提供NativeImage功能，作为数据消费者，主要用来将数据和OpenGL纹理对接，需在OpenGL环境下使用。 7 8**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 9 10**起始版本：** 9 11 12 13## 汇总 14 15 16### 文件 17 18| 名称 | 描述 | 19| -------- | -------- | 20| [native_image.h](native__image_8h.md) | 定义获取和使用NativeImage的相关函数。 | 21 22 23### 结构体 24 25| 名称 | 描述 | 26| -------- | -------- | 27| [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) | 一个OH_NativeImage的监听者，通过OH_NativeImage_SetOnFrameAvailableListener接口注册， 该监听结构体当有帧可用时，将触发回调。 | 28 29 30### 类型定义 31 32| 名称 | 描述 | 33| -------- | -------- | 34| [OH_NativeImage](#oh_nativeimage) | 提供OH_NativeImage结构体声明。 | 35| [OHNativeWindow](#ohnativewindow) | typedef struct NativeWindow<br/>提供对NativeWindow结构体声明。 | 36| [OH_OnFrameAvailable](#oh_onframeavailable) | 有buffer可获取时触发的回调函数。 | 37| [OH_OnFrameAvailableListener](#oh_onframeavailablelistener) | 一个OH_NativeImage的监听者，通过[OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener)接口注册， 该监听结构体，当有buffer可获取时，将触发回调给用户。 | 38 39 40### 函数 41 42| 名称 | 描述 | 43| -------- | -------- | 44| [OH_NativeImage_Create](#oh_nativeimage_create) (uint32_t textureId, uint32_t textureTarget) | 创建一个**OH_NativeImage**实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。 | 45| [OH_NativeImage_AcquireNativeWindow](#oh_nativeimage_acquirenativewindow) ([OH_NativeImage](#oh_nativeimage) \*image) | 获取与OH_NativeImage相关联的OHNativeWindow指针。 该OHNativeWindow后续不再需要时需要调用<br/>OH_NativeWindow_DestroyNativeWindow释放。 | 46| [OH_NativeImage_AttachContext](#oh_nativeimage_attachcontext) ([OH_NativeImage](#oh_nativeimage) \*image, uint32_t textureId) | 将OH_NativeImage实例附加到当前OpenGL ES上下文, 且该OpenGL ES纹理会绑定到<br/>GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新。 | 47| [OH_NativeImage_DetachContext](#oh_nativeimage_detachcontext) ([OH_NativeImage](#oh_nativeimage) \*image) | 将OH_NativeImage实例从当前OpenGL ES上下文分离。 | 48| [OH_NativeImage_UpdateSurfaceImage](#oh_nativeimage_updatesurfaceimage) ([OH_NativeImage](#oh_nativeimage) \*image) | 通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。 | 49| [OH_NativeImage_GetTimestamp](#oh_nativeimage_gettimestamp) ([OH_NativeImage](#oh_nativeimage) \*image) | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。 | 50| [OH_NativeImage_GetTransformMatrix](#oh_nativeimage_gettransformmatrix) ([OH_NativeImage](#oh_nativeimage) \*image, float matrix[16]) | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 | 51| [OH_NativeImage_GetSurfaceId](#oh_nativeimage_getsurfaceid) ([OH_NativeImage](#oh_nativeimage) \*image, uint64_t \*surfaceId) | 获取OH_NativeImage的surface编号。 | 52| [OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener) ([OH_NativeImage](#oh_nativeimage) \*image, [OH_OnFrameAvailableListener](_o_h___on_frame_available_listener.md) listener) | 设置帧可用回调。 | 53| [OH_NativeImage_UnsetOnFrameAvailableListener](#oh_nativeimage_unsetonframeavailablelistener) ([OH_NativeImage](#oh_nativeimage) \*image) | 取消设置帧可用回调。 | 54| [OH_NativeImage_Destroy](#oh_nativeimage_destroy) ([OH_NativeImage](#oh_nativeimage) \*\*image) | 销毁通过OH_NativeImage_Create创建的**OH_NativeImage**实例, 销毁后该**OH_NativeImage**指针会被赋值为空。 | 55 56 57## 类型定义说明 58 59 60### OH_NativeImage 61 62``` 63typedef struct OH_NativeImageOH_NativeImage 64``` 65 66**描述** 67 68提供OH_NativeImage结构体声明。 69 70**起始版本：** 9 71 72 73### OH_OnFrameAvailable 74 75``` 76typedef void(* OH_OnFrameAvailable) (void *context) 77``` 78 79**描述** 80 81有buffer可获取时触发的回调函数。 82 83**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 84 85**起始版本：** 11 86 87**参数:** 88 89| 名称 | 描述 | 90| -------- | -------- | 91| context | 用户自定义的上下文信息，会在回调触发时返回给用户。 | 92 93 94### OH_OnFrameAvailableListener 95 96``` 97typedef struct OH_OnFrameAvailableListener OH_OnFrameAvailableListener 98``` 99 100**描述** 101 102一个OH_NativeImage的监听者，通过[OH_NativeImage_SetOnFrameAvailableListener](#oh_nativeimage_setonframeavailablelistener)接口注册， 该监听结构体，当有buffer可获取时，将触发回调给用户。 103 104**起始版本：** 11 105 106 107### OHNativeWindow 108 109``` 110typedef struct NativeWindow OHNativeWindow 111``` 112 113**描述** 114 115提供对NativeWindow的访问功能。 116 117**起始版本：** 9 118 119 120## 函数说明 121 122 123### OH_NativeImage_AcquireNativeWindow() 124 125``` 126OHNativeWindow* OH_NativeImage_AcquireNativeWindow (OH_NativeImage * image) 127``` 128 129**描述** 130 131获取与OH_NativeImage相关联的OHNativeWindow指针. 该OHNativeWindow后续不再需要时需要调用 132 133OH_NativeWindow_DestroyNativeWindow释放。 134 135**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 136 137**起始版本：** 9 138 139**参数:** 140 141| 名称 | 描述 | 142| -------- | -------- | 143| image | 是指向**OH_NativeImage**实例的指针。 | 144 145**返回：** 146 147成功则返回一个指向OHNativeWindow实例的指针，否则返回**NULL**。 148 149 150### OH_NativeImage_AttachContext() 151 152``` 153int32_t OH_NativeImage_AttachContext (OH_NativeImage * image, uint32_t textureId ) 154``` 155 156**描述** 157 158将OH_NativeImage实例附加到当前OpenGL ES上下文, 且该OpenGL ES纹理会绑定到 159 160GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新。 161 162**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 163 164**起始版本：** 9 165 166**参数:** 167 168| 名称 | 描述 | 169| -------- | -------- | 170| image | 是指向**OH_NativeImage**实例的指针。 | 171| textureId | 是OH_NativeImage要附加到的OpenGL ES纹理的id。 | 172 173**返回：** 174 175返回值为0表示执行成功。 176 177 178### OH_NativeImage_Create() 179 180``` 181OH_NativeImage* OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget ) 182``` 183 184**描述** 185 186创建一个**OH_NativeImage**实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。 187 188**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 189 190**起始版本：** 9 191 192**参数:** 193 194| 名称 | 描述 | 195| -------- | -------- | 196| textureId | OpenGL ES的纹理ID，OH_NativeImage实例会与之相关联。 | 197| textureTarget | OpenGL ES的纹理目标。 | 198 199**返回：** 200 201返回一个指向**OH_NativeImage**实例的指针 returns **NULL** otherwise。 202 203 204### OH_NativeImage_Destroy() 205 206``` 207void OH_NativeImage_Destroy (OH_NativeImage ** image) 208``` 209 210**描述** 211 212销毁通过OH_NativeImage_Create创建的**OH_NativeImage**实例, 销毁后该 213 214**OH_NativeImage**指针会被赋值为空。 215 216**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 217 218**起始版本：** 9 219 220**参数:** 221 222| 名称 | 描述 | 223| -------- | -------- | 224| image | 是指向**OH_NativeImage**实例的指针。 | 225 226 227### OH_NativeImage_DetachContext() 228 229``` 230int32_t OH_NativeImage_DetachContext (OH_NativeImage * image) 231``` 232 233**描述** 234 235将OH_NativeImage实例从当前OpenGL ES上下文分离。 236 237**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 238 239**起始版本：** 9 240 241**参数:** 242 243| 名称 | 描述 | 244| -------- | -------- | 245| image | 是指向**OH_NativeImage**实例的指针。 | 246 247**返回：** 248 249返回值为0表示执行成功。 250 251 252### OH_NativeImage_GetSurfaceId() 253 254``` 255int32_t OH_NativeImage_GetSurfaceId (OH_NativeImage * image, uint64_t * surfaceId ) 256``` 257 258**描述** 259 260获取OH_NativeImage的surface编号。 261 262**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 263 264**起始版本：** 11 265 266**参数:** 267 268| 名称 | 描述 | 269| -------- | -------- | 270| image | 是指向**OH_NativeImage**实例的指针。 | 271| surfaceId | 是指向surface编号的指针。 | 272 273**返回：** 274 275返回值为0表示执行成功。 276 277 278### OH_NativeImage_GetTimestamp() 279 280``` 281int64_t OH_NativeImage_GetTimestamp (OH_NativeImage * image) 282``` 283 284**描述** 285 286获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。 287 288**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 289 290**起始版本：** 9 291 292**参数:** 293 294| 名称 | 描述 | 295| -------- | -------- | 296| image | 是指向**OH_NativeImage**实例的指针。 | 297 298**返回：** 299 300返回纹理图像的相关时间戳。 301 302 303### OH_NativeImage_GetTransformMatrix() 304 305``` 306int32_t OH_NativeImage_GetTransformMatrix (OH_NativeImage * image, float matrix[16] ) 307``` 308 309**描述** 310 311获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 312 313**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 314 315**起始版本：** 9 316 317**参数:** 318 319| 名称 | 描述 | 320| -------- | -------- | 321| image | 是指向**OH_NativeImage**实例的指针。 | 322| matrix | 用来存储要获取的4\*4的变化矩阵。 | 323 324**返回：** 325 326返回值为0表示执行成功。 327 328 329### OH_NativeImage_SetOnFrameAvailableListener() 330 331``` 332int32_t OH_NativeImage_SetOnFrameAvailableListener (OH_NativeImage * image, OH_OnFrameAvailableListener listener ) 333``` 334 335**描述** 336 337设置帧可用回调。 338 339**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 340 341**起始版本：** 11 342 343**参数:** 344 345| 名称 | 描述 | 346| -------- | -------- | 347| image | 是指向**OH_NativeImage**实例的指针。 | 348| listener | 表示回调监听者。 | 349 350**返回：** 351 352返回值为0表示执行成功。 353 354 355### OH_NativeImage_UnsetOnFrameAvailableListener() 356 357``` 358int32_t OH_NativeImage_UnsetOnFrameAvailableListener (OH_NativeImage * image) 359``` 360 361**描述** 362 363取消设置帧可用回调。 364 365**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 366 367**起始版本：** 11 368 369**参数:** 370 371| 名称 | 描述 | 372| -------- | -------- | 373| image | 是指向**OH_NativeImage**实例的指针。 | 374 375**返回：** 376 377返回值为0表示执行成功。 378 379 380### OH_NativeImage_UpdateSurfaceImage() 381 382``` 383int32_t OH_NativeImage_UpdateSurfaceImage (OH_NativeImage * image) 384``` 385 386**描述** 387 388通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。 389 390**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 391 392**起始版本：** 9 393 394**参数:** 395 396| 名称 | 描述 | 397| -------- | -------- | 398| image | 是指向**OH_NativeImage**实例的指针。 | 399 400**返回：** 401 402返回值为0表示执行成功。 403