1# native_image.h 2<!--Kit: ArkGraphics 2D--> 3<!--Subsystem: Graphics--> 4<!--Owner: @Flix-fangyang; @li_hui180; @ding-panyun--> 5<!--Designer: @conan13234--> 6<!--Tester: @nobuggers--> 7<!--Adviser: @ge-yafang--> 8## 概述 9 10定义获取和使用NativeImage的相关函数。 11 12<!--RP1--> 13相关示例：[NDKNativeImage](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Native/NdkNativeImage)<!--RP1End--> 14 15**引用文件：** <native_image/native_image.h> 16 17**库：** libnative_image.so 18 19**起始版本：** 9 20 21**相关模块：** [OH_NativeImage](capi-oh-nativeimage.md) 22 23## 汇总 24 25### 结构体 26 27| 名称 | typedef关键字 | 描述 | 28| -- | -- | -- | 29| [OH_OnFrameAvailableListener](capi-oh-nativeimage-oh-onframeavailablelistener.md) | OH_OnFrameAvailableListener | 一个OH_NativeImage的监听者，通过[OH_NativeImage_SetOnFrameAvailableListener](capi-native-image-h.md#oh_nativeimage_setonframeavailablelistener)接口注册该监听结构体，当有buffer可获取时，将触发回调给用户。 | 30| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md) | OH_NativeImage | 提供OH_NativeImage结构体声明。 | 31| [NativeWindow](capi-nativewindow-nativewindow.md) | OHNativeWindow | 提供对NativeWindow的访问功能。 | 32| [NativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) | OHNativeWindowBuffer | 提供NativeWindowBuffer结构体声明。 | 33 34### 函数 35 36| 名称 | typedef关键字 | 描述 | 37| -- | -- | -- | 38| [typedef void (\*OH_OnFrameAvailable)(void *context)](#oh_onframeavailable) | OH_OnFrameAvailable | 有buffer可获取时触发的回调函数。 | 39| [OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget)](#oh_nativeimage_create) | - | 创建一个OH_NativeImage实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。<br>本接口需要与[OH_NativeImage_Destroy](capi-native-image-h.md#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 | 40| [OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image)](#oh_nativeimage_acquirenativewindow) | - | 获取与OH_NativeImage相关联的OHNativeWindow指针。<br>本接口为非线程安全类型接口。<br>OH_NativeImage析构时会将对应的OHNativeWindow实例释放。若从本接口获取OHNativeWindow指针，当OH_NativeImage实例释放时，请将获取到的OHNativeWindow指针置空，防止后续产生野指针。 | 41| [int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId)](#oh_nativeimage_attachcontext) | - | 将OH_NativeImage实例附加到当前OpenGL ES上下文，且该OpenGL ES纹理会绑定到GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新。<br>本接口为非线程安全类型接口。 | 42| [int32_t OH_NativeImage_DetachContext(OH_NativeImage* image)](#oh_nativeimage_detachcontext) | - | 将OH_NativeImage实例从当前OpenGL ES上下文分离。<br>本接口为非线程安全类型接口。 | 43| [int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image)](#oh_nativeimage_updatesurfaceimage) | - | 通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。<br>本接口需要在Opengl ES环境上下文的线程中调用。<br>本接口需要在接收到[OH_OnFrameAvailableListener](capi-oh-nativeimage-oh-onframeavailablelistener.md)回调后调用。<br>本接口为非线程安全类型接口。 | 44| [int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image)](#oh_nativeimage_gettimestamp) | - | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。<br>本接口为非线程安全类型接口。 | 45| [int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16])](#oh_nativeimage_gettransformmatrix) | - | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 | 46| [int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId)](#oh_nativeimage_getsurfaceid) | - | 获取OH_NativeImage的surface编号。<br>本接口为非线程安全类型接口。 | 47| [int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener)](#oh_nativeimage_setonframeavailablelistener) | - | 设置帧可用回调。<br>不允许在回调函数中调用本模块的其他接口。<br>本接口为非线程安全类型接口。 | 48| [int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image)](#oh_nativeimage_unsetonframeavailablelistener) | - | 取消设置帧可用回调。<br>本接口为非线程安全类型接口。 | 49| [void OH_NativeImage_Destroy(OH_NativeImage** image)](#oh_nativeimage_destroy) | - | 销毁通过OH_NativeImage_Create创建的OH_NativeImage实例, 销毁后该<br>OH_NativeImage指针会被赋值为空。<br>本接口为非线程安全类型接口。 | 50| [int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16])](#oh_nativeimage_gettransformmatrixv2) | - | 根据生产端设置的旋转角度，获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。<br>matrix在[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口调用后，才会更新。<br>本接口为非线程安全类型接口。 | 51| [int32_t OH_NativeImage_GetBufferMatrix(OH_NativeImage* image, float matrix[16])](#oh_nativeimage_getbuffermatrix) | - | 获取根据生产端设置的旋转角度和buffer实际有效内容区域计算出的变换矩阵。<br>本接口返回一个变换矩阵，该矩阵是[OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)在消费buffer，即调用[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)或者[OH_NativeImage_AcquireNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_acquirenativewindowbuffer)时，根据buffer的旋转角度和实际有效内容区域计算所得。<br>本接口为非线程安全类型接口。 | 52| [int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd)](#oh_nativeimage_acquirenativewindowbuffer) | - | 通过消费端的OH_NativeImage获取一个OHNativeWindowBuffer。<br>本接口不能与[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口同时使用。<br>本接口将会创建一个OHNativeWindowBuffer。<br>当使用OHNativeWindowBuffer时，用户需要通过[OH_NativeWindow_NativeObjectReference](capi-external-window-h.md#oh_nativewindow_nativeobjectreference)接口将其引用计数加一。<br>当OHNativeWindowBuffer使用完，用户需要通过[OH_NativeWindow_NativeObjectUnreference](capi-external-window-h.md#oh_nativewindow_nativeobjectunreference)接口将其引用计数减一。<br>本接口需要和[OH_NativeImage_ReleaseNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_releasenativewindowbuffer)接口配合使用，否则会存在内存泄露。<br>当fenceFd使用完，用户需要将其close。<br>本接口为非线程安全类型接口。 | 53| [int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd)](#oh_nativeimage_releasenativewindowbuffer) | - | 通过OH_NativeImage实例将OHNativeWindowBuffer归还到buffer队列中。<br>系统会将fenceFd关闭，无需用户close。<br>本接口为非线程安全类型接口。 | 54| [OH_NativeImage* OH_ConsumerSurface_Create(void)](#oh_consumersurface_create) | - | 创建一个OH_NativeImage实例，作为surface的消费端。<br>本接口仅用于surface消费端的内存轮转，创建的OH_NativeImage内部不会主动进行内存渲染处理。<br>本接口不能与[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口同时使用。<br>本接口与[OH_NativeImage_AcquireNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_acquirenativewindowbuffer)和[OH_NativeImage_ReleaseNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_releasenativewindowbuffer)配合使用。<br>本接口需要和[OH_NativeImage_Destroy](capi-native-image-h.md#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 | 55| [int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage)](#oh_consumersurface_setdefaultusage) | - | 设置默认读写方式。<br>本接口为非线程安全类型接口。 | 56| [int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height)](#oh_consumersurface_setdefaultsize) | - | 设置几何图形默认尺寸。<br>本接口为非线程安全类型接口。 | 57| [int32_t OH_NativeImage_SetDropBufferMode(OH_NativeImage* image, bool isOpen)](#oh_nativeimage_setdropbuffermode) | - | 设置OH_NativeImage是否为渲染丢帧模式。<br>处于此模式时，大部分生产端生产的buffer将会被丢弃，最新的buffer会及时上屏渲染。<br>此模式不能同时保证帧率高的要求。<br>此接口建议在[OH_NativeImage_Create](capi-native-image-h.md#oh_nativeimage_create)接口调用后立即调用。<br>此接口在与[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口一起使用的场景下才会生效。<br>本接口为非线程安全类型接口。<br> | 58 59## 函数说明 60 61### OH_OnFrameAvailable() 62 63``` 64typedef void (*OH_OnFrameAvailable)(void *context) 65``` 66 67**描述** 68 69有buffer可获取时触发的回调函数。 70 71**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 72 73**起始版本：** 11 74 75 76**参数：** 77 78| 参数项 | 描述 | 79| -- | -- | 80| void *context | 用户自定义的上下文信息，会在回调触发时返回给用户。 | 81 82### OH_NativeImage_Create() 83 84``` 85OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget) 86``` 87 88**描述** 89 90创建一个OH_NativeImage实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。<br>本接口需要与[OH_NativeImage_Destroy](capi-native-image-h.md#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 91 92**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 93 94**起始版本：** 9 95 96 97**参数：** 98 99| 参数项 | 描述 | 100| -- | -- | 101| uint32_t textureId | OpenGL ES的纹理ID，OH_NativeImage实例会与之相关联。 | 102| uint32_t textureTarget | OpenGL ES的纹理目标。 | 103 104**返回：** 105 106| 类型 | 说明 | 107| -- | -- | 108| OH_NativeImage* | 创建成功则返回一个指向OH_NativeImage实例的指针，否则返回NULL。 | 109 110### OH_NativeImage_AcquireNativeWindow() 111 112``` 113OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image) 114``` 115 116**描述** 117 118获取与OH_NativeImage相关联的OHNativeWindow指针。<br>本接口为非线程安全类型接口。<br>OH_NativeImage析构时会将对应的OHNativeWindow实例释放。若从本接口获取OHNativeWindow指针，当OH_NativeImage实例释放时，请将获取到的OHNativeWindow指针置空，防止后续产生野指针。 119 120**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 121 122**起始版本：** 9 123 124 125**参数：** 126 127| 参数项 | 描述 | 128| -- | -- | 129| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 130 131**返回：** 132 133| 类型 | 说明 | 134| -- | -- | 135| [OHNativeWindow](capi-nativewindow-nativewindow.md)* | 成功则返回一个指向OHNativeWindow实例的指针，否则返回NULL。 | 136 137### OH_NativeImage_AttachContext() 138 139``` 140int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId) 141``` 142 143**描述** 144 145将OH_NativeImage实例附加到当前OpenGL ES上下文，且该OpenGL ES纹理会绑定到GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新。<br>本接口为非线程安全类型接口。 146 147**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 148 149**起始版本：** 9 150 151 152**参数：** 153 154| 参数项 | 描述 | 155| -- | -- | 156| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 157| uint32_t textureId | 是OH_NativeImage要附加到的OpenGL ES纹理的id。 | 158 159**返回：** 160 161| 类型 | 说明 | 162| -- | -- | 163| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 164 165### OH_NativeImage_DetachContext() 166 167``` 168int32_t OH_NativeImage_DetachContext(OH_NativeImage* image) 169``` 170 171**描述** 172 173将OH_NativeImage实例从当前OpenGL ES上下文分离。<br>本接口为非线程安全类型接口。 174 175**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 176 177**起始版本：** 9 178 179 180**参数：** 181 182| 参数项 | 描述 | 183| -- | -- | 184| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 185 186**返回：** 187 188| 类型 | 说明 | 189| -- | -- | 190| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 191 192### OH_NativeImage_UpdateSurfaceImage() 193 194``` 195int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image) 196``` 197 198**描述** 199 200通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。<br>本接口需要在Opengl ES环境上下文的线程中调用。<br>本接口需要在接收到[OH_OnFrameAvailableListener](capi-oh-nativeimage-oh-onframeavailablelistener.md)回调后调用。<br>本接口为非线程安全类型接口。 201 202**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 203 204**起始版本：** 9 205 206 207**参数：** 208 209| 参数项 | 描述 | 210| -- | -- | 211| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 212 213**返回：** 214 215| 类型 | 说明 | 216| -- | -- | 217| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 218 219### OH_NativeImage_GetTimestamp() 220 221``` 222int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image) 223``` 224 225**描述** 226 227获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。<br>本接口为非线程安全类型接口。 228 229**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 230 231**起始版本：** 9 232 233 234**参数：** 235 236| 参数项 | 描述 | 237| -- | -- | 238| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 239 240**返回：** 241 242| 类型 | 说明 | 243| -- | -- | 244| int64_t | 返回纹理图像的相关时间戳。 | 245 246### OH_NativeImage_GetTransformMatrix() 247 248``` 249int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16]) 250``` 251 252**描述** 253 254获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 255 256**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 257 258**起始版本：** 9 259 260**废弃版本：** 从API version 12开始废弃。 261 262**替代接口：** [OH_NativeImage_GetTransformMatrixV2](capi-native-image-h.md#oh_nativeimage_gettransformmatrixv2) 263 264 265**参数：** 266 267| 参数项 | 描述 | 268| -- | -- | 269| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 270| matrix | 用来存储要获取的4*4的变化矩阵。 | 271 272**返回：** 273 274| 类型 | 说明 | 275| -- | -- | 276| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 277 278### OH_NativeImage_GetSurfaceId() 279 280``` 281int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId) 282``` 283 284**描述** 285 286获取OH_NativeImage的surface编号。<br>本接口为非线程安全类型接口。 287 288**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 289 290**起始版本：** 11 291 292 293**参数：** 294 295| 参数项 | 描述 | 296| -- | -- | 297| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 298| uint64_t* surfaceId | 是指向surface编号的指针。 | 299 300**返回：** 301 302| 类型 | 说明 | 303| -- | -- | 304| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 305 306### OH_NativeImage_SetOnFrameAvailableListener() 307 308``` 309int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener) 310``` 311 312**描述** 313 314设置帧可用回调。<br>不允许在回调函数中调用本模块的其他接口。<br>本接口为非线程安全类型接口。 315 316**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 317 318**起始版本：** 11 319 320 321**参数：** 322 323| 参数项 | 描述 | 324| -- | -- | 325| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 326| [OH_OnFrameAvailableListener](capi-oh-nativeimage-oh-onframeavailablelistener.md) listener | 表示回调监听者。 | 327 328**返回：** 329 330| 类型 | 说明 | 331| -- | -- | 332| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 333 334### OH_NativeImage_UnsetOnFrameAvailableListener() 335 336``` 337int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image) 338``` 339 340**描述** 341 342取消设置帧可用回调。<br>本接口为非线程安全类型接口。 343 344**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 345 346**起始版本：** 11 347 348 349**参数：** 350 351| 参数项 | 描述 | 352| -- | -- | 353| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 354 355**返回：** 356 357| 类型 | 说明 | 358| -- | -- | 359| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 360 361### OH_NativeImage_Destroy() 362 363``` 364void OH_NativeImage_Destroy(OH_NativeImage** image) 365``` 366 367**描述** 368 369销毁通过OH_NativeImage_Create创建的OH_NativeImage实例, 销毁后该<br>OH_NativeImage指针会被赋值为空。<br>本接口为非线程安全类型接口。 370 371**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 372 373**起始版本：** 9 374 375 376**参数：** 377 378| 参数项 | 描述 | 379| -- | -- | 380| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)** image | 指向OH_NativeImage实例的指针。 | 381 382### OH_NativeImage_GetTransformMatrixV2() 383 384``` 385int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16]) 386``` 387 388**描述** 389 390根据生产端设置的旋转角度，获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。<br>matrix在[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口调用后，才会更新。<br>本接口为非线程安全类型接口。 391 392**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 393 394**起始版本：** 12 395 396 397**参数：** 398 399| 参数项 | 描述 | 400| -- | -- | 401| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 402| matrix | 用来存储要获取的4*4的变化矩阵。 | 403 404**返回：** 405 406| 类型 | 说明 | 407| -- | -- | 408| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 409 410### OH_NativeImage_GetBufferMatrix() 411 412``` 413int32_t OH_NativeImage_GetBufferMatrix(OH_NativeImage* image, float matrix[16]) 414``` 415 416**描述** 417 418获取根据生产端设置的旋转角度和buffer实际有效内容区域计算出的变换矩阵。<br>本接口返回一个变换矩阵，该矩阵是[OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)在消费buffer，即调用[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)或者[OH_NativeImage_AcquireNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_acquirenativewindowbuffer)时，根据buffer的旋转角度和实际有效内容区域计算所得。<br>本接口为非线程安全类型接口。 419 420**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 421 422**起始版本：** 15 423 424 425**参数：** 426 427| 参数项 | 描述 | 428| -- | -- | 429| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向[OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)实例的指针。 | 430| matrix | 用于存储获取的4*4变换矩阵。 | 431 432**返回：** 433 434| 类型 | 说明 | 435| -- | -- | 436| int32_t | 返回接口执行结果。NATIVE_ERROR_OK，表示接口执行成功。<br> 返回NATIVE_ERROR_INVALID_ARGUMENTS，对应错误码为40001000，表示image参数为空。<br> 返回NATIVE_ERROR_MEM_OPERATION_ERROR，对应错误码为30001000，表示内存操作错误，获取变换矩阵失败。 | 437 438### OH_NativeImage_AcquireNativeWindowBuffer() 439 440``` 441int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd) 442``` 443 444**描述** 445 446通过消费端的OH_NativeImage获取一个OHNativeWindowBuffer。本接口不能与[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口同时使用。<br>本接口将会创建一个OHNativeWindowBuffer。当使用OHNativeWindowBuffer<时，用户需要通过[OH_NativeWindow_NativeObjectReference](capi-external-window-h.md#oh_nativewindow_nativeobjectreference)接口将其引用计数加一。当OHNativeWindowBuffer使用完，用户需要通过[OH_NativeWindow_NativeObjectUnreference](capi-external-window-h.md#oh_nativewindow_nativeobjectunreference)接口将其引用计数减一。<br>本接口需要和[OH_NativeImage_ReleaseNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_releasenativewindowbuffer)接口配合使用，否则会存在内存泄露。<br>当fenceFd使用完，用户需要将其close。<br>本接口为非线程安全类型接口。 447 448**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 449 450**起始版本：** 12 451 452 453**参数：** 454 455| 参数项 | 描述 | 456| -- | -- | 457| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 458| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md)** nativeWindowBuffer | 指向OHNativeWindowBuffer指针的指针。 | 459| int* fenceFd | 指向文件描述符句柄的指针。 | 460 461**返回：** 462 463| 类型 | 说明 | 464| -- | -- | 465| int32_t | 执行成功时返回NATIVE_ERROR_OK。<br> image, nativeWindowBuffer, fenceFd是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。<br> 没有buffer可以消费时返回NATIVE_ERROR_NO_BUFFER。 | 466 467### OH_NativeImage_ReleaseNativeWindowBuffer() 468 469``` 470int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd) 471``` 472 473**描述** 474 475通过OH_NativeImage实例将OHNativeWindowBuffer归还到buffer队列中。<br>系统会将fenceFd关闭，无需用户close。<br>本接口为非线程安全类型接口。 476 477**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 478 479**起始版本：** 12 480 481 482**参数：** 483 484| 参数项 | 描述 | 485| -- | -- | 486| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 487| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md)* nativeWindowBuffer | 指向OHNativeWindowBuffer实例的指针。 | 488| int fenceFd | 指向文件描述符句柄, 用于并发同步控制。 | 489 490**返回：** 491 492| 类型 | 说明 | 493| -- | -- | 494| int32_t | 执行成功时返回NATIVE_ERROR_OK。<br> image, nativeWindowBuffer是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。<br> nativeWindowBuffer为状态非法时返回NATIVE_ERROR_BUFFER_STATE_INVALID。<br> nativeWindowBuffer不在缓存中返回NATIVE_ERROR_BUFFER_NOT_IN_CACHE。 | 495 496### OH_ConsumerSurface_Create() 497 498``` 499OH_NativeImage* OH_ConsumerSurface_Create(void) 500``` 501 502**描述** 503 504创建一个OH_NativeImage实例，作为surface的消费端。<br>本接口仅用于surface消费端的内存轮转，创建的OH_NativeImage内部不会主动进行内存渲染处理。<br>本接口不能与[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口同时使用。<br>本接口与[OH_NativeImage_AcquireNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_acquirenativewindowbuffer)和[OH_NativeImage_ReleaseNativeWindowBuffer](capi-native-image-h.md#oh_nativeimage_releasenativewindowbuffer)配合使用。<br>本接口需要和[OH_NativeImage_Destroy](capi-native-image-h.md#oh_nativeimage_destroy)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 505 506**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 507 508**起始版本：** 12 509 510**返回：** 511 512| 类型 | 说明 | 513| -- | -- | 514| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* | 成功则返回一个指向OH_NativeImage实例的指针，否则返回NULL。 | 515 516### OH_ConsumerSurface_SetDefaultUsage() 517 518``` 519int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage) 520``` 521 522**描述** 523 524设置默认读写方式。<br>本接口为非线程安全类型接口。 525 526**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 527 528**起始版本：** 13 529 530 531**参数：** 532 533| 参数项 | 描述 | 534| -- | -- | 535| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 536| uint64_t usage | 表示读写方式。枚举值参考[OH_NativeBuffer_Usage](capi-native-buffer-h.md#oh_nativebuffer_usage)。 | 537 538**返回：** 539 540| 类型 | 说明 | 541| -- | -- | 542| int32_t | 执行成功时返回NATIVE_ERROR_OK。<br> image是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 | 543 544### OH_ConsumerSurface_SetDefaultSize() 545 546``` 547int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height) 548``` 549 550**描述** 551 552设置几何图形默认尺寸。<br>本接口为非线程安全类型接口。 553 554**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 555 556**起始版本：** 13 557 558 559**参数：** 560 561| 参数项 | 描述 | 562| -- | -- | 563| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 564| int32_t width | 表示几何图形宽度，取值范围大于0，单位为像素。 | 565| int32_t height | 表示几何图形高度，取值范围大于0，单位为像素。 | 566 567**返回：** 568 569| 类型 | 说明 | 570| -- | -- | 571| int32_t | 执行成功时返回NATIVE_ERROR_OK。<br> image是空指针时，或width、height小于等于0时返回NATIVE_ERROR_INVALID_ARGUMENTS。 | 572 573### OH_NativeImage_SetDropBufferMode() 574 575``` 576int32_t OH_NativeImage_SetDropBufferMode(OH_NativeImage* image, bool isOpen) 577``` 578 579**描述** 580 581设置OH_NativeImage是否为渲染丢帧模式。<br>处于此模式时，大部分生产端生产的buffer将会被丢弃，最新的buffer会及时上屏渲染。<br>此模式不能同时保证帧率高的要求。<br>此接口建议在[OH_NativeImage_Create](capi-native-image-h.md#oh_nativeimage_create)接口调用后立即调用。<br>此接口在与[OH_NativeImage_UpdateSurfaceImage](capi-native-image-h.md#oh_nativeimage_updatesurfaceimage)接口一起使用的场景下才会生效。<br>本接口为非线程安全类型接口。<br>通过[OH_NativeImage_SetOnFrameAvailableListener](capi-native-image-h.md#oh_nativeimage_setonframeavailablelistener)设置的listener回调不会因为设置了丢帧模式而减少。<br> 582 583**系统能力：** SystemCapability.Graphic.Graphic2D.NativeImage 584 585**起始版本：** 17 586 587 588**参数：** 589 590| 参数项 | 描述 | 591| -- | -- | 592| [OH_NativeImage](capi-oh-nativeimage-oh-nativeimage.md)* image | 指向OH_NativeImage实例的指针。 | 593| bool isOpen | 是否设置渲染丢帧。true表示设置为渲染丢帧模式，false表示不设置。 | 594 595**返回：** 596 597| 类型 | 说明 | 598| -- | -- | 599| int32_t | 执行成功时返回NATIVE_ERROR_OK。<br> image是空指针时返回NATIVE_ERROR_INVALID_ARGUMENTS。 | 600 601 602