1# external_window.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定义获取和使用NativeWindow的相关函数。 11 12<!--RP1--> 13**相关示例：** [NDKNativeWindow](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Native/NdkNativeWindow)<!--RP1End--> 14 15**引用文件：** <native_window/external_window.h> 16 17**库：** libnative_window.so 18 19**起始版本：** 8 20 21**相关模块：** [NativeWindow](capi-nativewindow.md) 22 23## 汇总 24 25### 结构体 26 27| 名称 | typedef关键字 | 描述 | 28| -- | -- | -- | 29| [Region](capi-nativewindow-region.md) | Region | 表示本地窗口OHNativeWindow需要更新内容的矩形区域（脏区）。 | 30| [Rect](capi-nativewindow-rect.md) | - | 如果rects是空指针nullptr，默认Buffer大小为脏区。 | 31| [OHHDRMetaData](capi-nativewindow-ohhdrmetadata.md) | OHHDRMetaData | HDR元数据结构体定义。 | 32| [OHExtDataHandle](capi-nativewindow-ohextdatahandle.md) | OHExtDataHandle | 扩展数据句柄结构体定义。 | 33| [OHIPCParcel](capi-nativewindow-ohipcparcel.md) | OHIPCParcel | 提供对IPC序列化对象的访问功能。 | 34| [NativeWindow](capi-nativewindow-nativewindow.md) | OHNativeWindow | 提供对OHNativeWindow的访问功能。 | 35| [NativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) | OHNativeWindowBuffer | 提供对OHNativeWindowBuffer的访问功能。 | 36 37### 枚举 38 39| 名称 | typedef关键字 | 描述 | 40| -- | -- | -- | 41| [NativeWindowOperation](#nativewindowoperation) | NativeWindowOperation | OH_NativeWindow_NativeWindowHandleOpt函数中的操作码。 | 42| [OHScalingMode](#ohscalingmode) | OHScalingMode | 缩放模式Scaling Mode。 | 43| [OHScalingModeV2](#ohscalingmodev2) | OHScalingModeV2 | 渲染缩放模式枚举。 | 44| [OHHDRMetadataKey](#ohhdrmetadatakey) | OHHDRMetadataKey | 枚举HDR元数据关键字。 | 45| [OHSurfaceSource](#ohsurfacesource) | OHSurfaceSource | 本地窗口内容来源类型枚举。 | 46 47### 函数 48 49| 名称 | 描述 | 50| -- | -- | 51| [OHNativeWindow* OH_NativeWindow_CreateNativeWindow(void* pSurface)](#oh_nativewindow_createnativewindow) | 创建OHNativeWindow实例，每次调用都会产生一个新的OHNativeWindow实例。<br>说明：此接口不可用，可通过OH_NativeImage_AcquireNativeWindow创建，或通过XComponent创建。 | 52| [void OH_NativeWindow_DestroyNativeWindow(OHNativeWindow* window)](#oh_nativewindow_destroynativewindow) | 将OHNativeWindow对象的引用计数减1，当引用计数为0的时候，该OHNativeWindow对象会被析构掉。<br>本接口为非线程安全类型接口。 | 53| [OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer(void* pSurfaceBuffer)](#oh_nativewindow_createnativewindowbufferfromsurfacebuffer) | 创建OHNativeWindowBuffer实例，每次调用都会产生一个新的OHNativeWindowBuffer实例。<br>说明：此接口不可用，使用OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer替代。 | 54| [OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer(OH_NativeBuffer* nativeBuffer)](#oh_nativewindow_createnativewindowbufferfromnativebuffer) | 创建OHNativeWindowBuffer实例，每次调用都会产生一个新的OHNativeWindowBuffer实例。<br>本接口需要与[OH_NativeWindow_DestroyNativeWindowBuffer](#oh_nativewindow_destroynativewindowbuffer)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 | 55| [void OH_NativeWindow_DestroyNativeWindowBuffer(OHNativeWindowBuffer* buffer)](#oh_nativewindow_destroynativewindowbuffer) | 将OHNativeWindowBuffer对象的引用计数减1，当引用计数为0的时候，该OHNativeWindowBuffer对象会被析构掉。<br>本接口为非线程安全类型接口。 | 56| [int32_t OH_NativeWindow_NativeWindowRequestBuffer(OHNativeWindow *window,OHNativeWindowBuffer **buffer, int *fenceFd)](#oh_nativewindow_nativewindowrequestbuffer) | 通过OHNativeWindow对象申请一块OHNativeWindowBuffer，用以内容生产。<br>在调用本接口前，需要通过[SET_BUFFER_GEOMETRY](#nativewindowoperation)对OHNativeWindow设置宽高。<br>本接口需要与[OH_NativeWindow_NativeWindowFlushBuffer](#oh_nativewindow_nativewindowflushbuffer)接口配合使用，否则内存会耗尽。<br>当fenceFd使用完，用户需要将其close。<br>本接口为非线程安全类型接口。 | 57| [int32_t OH_NativeWindow_NativeWindowFlushBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer,int fenceFd, Region region)](#oh_nativewindow_nativewindowflushbuffer) | 通过OHNativeWindow将生产好内容的OHNativeWindowBuffer放回到Buffer队列中，用以内容消费。<br>系统会将fenceFd关闭，无需用户close。<br>本接口为非线程安全类型接口。 | 58| [int32_t OH_NativeWindow_GetLastFlushedBuffer(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16])](#oh_nativewindow_getlastflushedbuffer) | 从OHNativeWindow获取上次送回到buffer队列中的OHNativeWindowBuffer。 | 59| [int32_t OH_NativeWindow_NativeWindowAbortBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer)](#oh_nativewindow_nativewindowabortbuffer) | 通过OHNativeWindow将之前申请出来的OHNativeWindowBuffer返还到Buffer队列中，供下次再申请。<br>本接口为非线程安全类型接口。 | 60| [int32_t OH_NativeWindow_NativeWindowHandleOpt(OHNativeWindow *window, int code, ...)](#oh_nativewindow_nativewindowhandleopt) | 设置/获取OHNativeWindow的属性，包括设置/获取宽高、内容格式等。<br>本接口为非线程安全类型接口。 | 61| [BufferHandle *OH_NativeWindow_GetBufferHandleFromNative(OHNativeWindowBuffer *buffer)](#oh_nativewindow_getbufferhandlefromnative) | 通过OHNativeWindowBuffer获取该buffer的BufferHandle指针。<br>本接口为非线程安全类型接口。 | 62| [int32_t OH_NativeWindow_NativeObjectReference(void *obj)](#oh_nativewindow_nativeobjectreference) | 增加一个NativeObject的引用计数。<br>本接口需要与[OH_NativeWindow_NativeObjectUnreference](#oh_nativewindow_nativeobjectunreference)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 | 63| [int32_t OH_NativeWindow_NativeObjectUnreference(void *obj)](#oh_nativewindow_nativeobjectunreference) | 减少一个NativeObject的引用计数，当引用计数减少为0时，该NativeObject将被析构掉。<br>本接口为非线程安全类型接口。 | 64| [int32_t OH_NativeWindow_GetNativeObjectMagic(void *obj)](#oh_nativewindow_getnativeobjectmagic) | 获取NativeObject的MagicId。<br>本接口为非线程安全类型接口。 | 65| [int32_t OH_NativeWindow_NativeWindowSetScalingMode(OHNativeWindow *window, uint32_t sequence,OHScalingMode scalingMode)](#oh_nativewindow_nativewindowsetscalingmode) | 设置OHNativeWindow的ScalingMode。 | 66| [int32_t OH_NativeWindow_NativeWindowSetMetaData(OHNativeWindow *window, uint32_t sequence, int32_t size,const OHHDRMetaData *metaData)](#oh_nativewindow_nativewindowsetmetadata) | 设置OHNativeWindow的元数据。 | 67| [int32_t OH_NativeWindow_NativeWindowSetMetaDataSet(OHNativeWindow *window, uint32_t sequence, OHHDRMetadataKey key,int32_t size, const uint8_t *metaData)](#oh_nativewindow_nativewindowsetmetadataset) | 设置OHNativeWindow的元数据集。 | 68| [int32_t OH_NativeWindow_NativeWindowSetTunnelHandle(OHNativeWindow *window, const OHExtDataHandle *handle)](#oh_nativewindow_nativewindowsettunnelhandle) | 设置OHNativeWindow的TunnelHandle。 | 69| [int32_t OH_NativeWindow_NativeWindowAttachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer)](#oh_nativewindow_nativewindowattachbuffer) | 将OHNativeWindowBuffer添加进OHNativeWindow中。<br>本接口需要与[OH_NativeWindow_NativeWindowDetachBuffer](#oh_nativewindow_nativewindowdetachbuffer)接口配合使用，否则会存在内存管理混乱问题。<br>本接口为非线程安全类型接口。<br> | 70| [int32_t OH_NativeWindow_NativeWindowDetachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer)](#oh_nativewindow_nativewindowdetachbuffer) | 将OHNativeWindowBuffer从OHNativeWindow中分离。<br>本接口为非线程安全类型接口。 | 71| [int32_t OH_NativeWindow_GetSurfaceId(OHNativeWindow *window, uint64_t *surfaceId)](#oh_nativewindow_getsurfaceid) | 通过OHNativeWindow获取对应的surfaceId。<br>本接口为非线程安全类型接口。 | 72| [int32_t OH_NativeWindow_CreateNativeWindowFromSurfaceId(uint64_t surfaceId, OHNativeWindow **window)](#oh_nativewindow_createnativewindowfromsurfaceid) | 通过surfaceId创建对应的OHNativeWindow。<br>本接口需要与[OH_NativeWindow_DestroyNativeWindow](#oh_nativewindow_destroynativewindow)接口配合使用，否则会存在内存泄露。<br>如果存在并发释放OHNativeWindow的情况，需要通过[OH_NativeWindow_NativeObjectReference](#oh_nativewindow_nativeobjectreference)和[OH_NativeWindow_NativeObjectUnreference](#oh_nativewindow_nativeobjectunreference)对OHNativeWindow进行引用计数加一和减一。<br>通过surfaceId获取的surface需要是在本进程中创建的，不能跨进程获取surface。<br>本接口为非线程安全类型接口。 | 73| [int32_t OH_NativeWindow_NativeWindowSetScalingModeV2(OHNativeWindow* window, OHScalingModeV2 scalingMode)](#oh_nativewindow_nativewindowsetscalingmodev2) | 设置OHNativeWindow的渲染缩放模式。<br>本接口为非线程安全类型接口。 | 74| [int32_t OH_NativeWindow_GetLastFlushedBufferV2(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16])](#oh_nativewindow_getlastflushedbufferv2) | 从OHNativeWindow获取上次送回到buffer队列中的OHNativeWindowBuffer,与OH_NativeWindow_GetLastFlushedBuffer的差异在于matrix不同。<br>本接口需要与[OH_NativeWindow_NativeObjectUnreference](#oh_nativewindow_nativeobjectunreference)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 | 75| [void OH_NativeWindow_SetBufferHold(OHNativeWindow *window)](#oh_nativewindow_setbufferhold) | 提前缓存一帧buffer，且缓存的这一帧延迟一帧上屏显示，以此抵消后续一次超长帧丢帧。<br>本接口为非线程安全类型接口。 | 76| [int32_t OH_NativeWindow_WriteToParcel(OHNativeWindow *window, OHIPCParcel *parcel)](#oh_nativewindow_writetoparcel) | 将窗口对象写入IPC序列化对象中。<br>本接口为非线程安全类型接口。 | 77| [int32_t OH_NativeWindow_ReadFromParcel(OHIPCParcel *parcel, OHNativeWindow **window)](#oh_nativewindow_readfromparcel) | 从IPC序列化对象中读取窗口对象。<br>本接口为非线程安全类型接口。 | 78| [int32_t OH_NativeWindow_SetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace colorSpace)](#oh_nativewindow_setcolorspace) | 为OHNativeWindow设置颜色空间属性。<br>本接口为非线程安全类型接口。 | 79| [int32_t OH_NativeWindow_GetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace *colorSpace)](#oh_nativewindow_getcolorspace) | 获取OHNativeWindow颜色空间属性。<br>本接口为非线程安全类型接口。 | 80| [int32_t OH_NativeWindow_SetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t size, uint8_t *metadata)](#oh_nativewindow_setmetadatavalue) | 为OHNativeWindow设置元数据属性值。<br>本接口为非线程安全类型接口。 | 81| [int32_t OH_NativeWindow_GetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t *size, uint8_t **metadata)](#oh_nativewindow_getmetadatavalue) | 获取OHNativeWindow元数据属性值。<br>本接口为非线程安全类型接口。 | 82| [int32_t OH_NativeWindow_CleanCache(OHNativeWindow *window)](#oh_nativewindow_cleancache) | 清理OHNativeWindow中的OHNativeWindowBuffer缓存。<br>使用该接口清理缓存前，需确保已通过[OH_NativeWindow_NativeWindowRequestBuffer](#oh_nativewindow_nativewindowrequestbuffer)接口成功申请OHNativeWindowBuffer。<br>本接口为非线程安全类型接口。 | 83 84## 枚举类型说明 85 86### NativeWindowOperation 87 88``` 89enum NativeWindowOperation 90``` 91 92**描述** 93 94OH_NativeWindow_NativeWindowHandleOpt函数中的操作码。 95 96**起始版本：** 8 97 98| 枚举项 | 描述 | 99| -- | -- | 100| SET_BUFFER_GEOMETRY | 设置本地窗口缓冲区几何图形，函数中的可变参数是[输入] int32_t width，[输入] int32_t height。 | 101| GET_BUFFER_GEOMETRY | 获取本地窗口缓冲区几何图形，函数中的可变参数是[输出] int32_t height，[输入] int32_t width。 | 102| GET_FORMAT | 获取本地窗口缓冲区格式，函数中的可变参数是[输出] int32_tformat，取值具体可见[OH_NativeBuffer_Format](capi-native-buffer-h.md#oh_nativebuffer_format)枚举值。 | 103| SET_FORMAT | 设置本地窗口缓冲区格式，函数中的可变参数是[输入] int32_t format，取值具体可见[OH_NativeBuffer_Format](capi-native-buffer-h.md#oh_nativebuffer_format)枚举值。 | 104| GET_USAGE | 获取本地窗口读写方式，函数中的可变参数是[输出] uint64_tusage，取值具体可见[OH_NativeBuffer_Usage](capi-native-buffer-h.md#oh_nativebuffer_usage)枚举值。 | 105| SET_USAGE | 设置本地窗口缓冲区读写方式，函数中的可变参数是[输入] uint64_t usage，取值具体可见[OH_NativeBuffer_Usage](capi-native-buffer-h.md#oh_nativebuffer_usage)枚举值。 | 106| SET_STRIDE | 设置本地窗口缓冲区步幅，函数中的可变参数是[输入] int32_t stride。<br/>**废弃版本：** 16 | 107| GET_STRIDE | 获取本地窗口缓冲区步幅，函数中的可变参数是[输出] int32_t *stride。<br/>**废弃版本：** 16<br/>**替代方案：** 使用[OH_NativeWindow_GetBufferHandleFromNative](#oh_nativewindow_getbufferhandlefromnative)接口获取BufferHandle实例，从[BufferHandle](capi-nativewindow-bufferhandle.md)实例中获取stride值。 | 108| SET_SWAP_INTERVAL | 设置本地窗口缓冲区交换间隔，函数中的可变参数是[输入] int32_t interval。 | 109| GET_SWAP_INTERVAL | 获取本地窗口缓冲区交换间隔，函数中的可变参数是[输出] int32_tinterval。 | 110| SET_TIMEOUT | 设置请求本地窗口请求缓冲区的超时等待时间，未手动设置时默认值为3000毫秒，函数中的可变参数是[输入] int32_t timeout, 单位为毫秒。 | 111| GET_TIMEOUT | 获取请求本地窗口请求缓冲区的超时等待时间，未手动设置时默认值为3000毫秒，函数中的可变参数是[输出] int32_t timeout，单位为毫秒。 | 112| SET_COLOR_GAMUT | 设置本地窗口缓冲区色彩空间，函数中的可变参数是[输入] int32_t colorGamut，取值具体可见[OH_NativeBuffer_ColorGamut](capi-native-buffer-h.md#oh_nativebuffer_colorgamut)枚举值。 | 113| GET_COLOR_GAMUT | 获取本地窗口缓冲区色彩空间，函数中的可变参数是[输出] int32_tcolorGamut，取值具体可见[OH_NativeBuffer_ColorGamut](capi-native-buffer-h.md#oh_nativebuffer_colorgamut)枚举值。 | 114| SET_TRANSFORM | 设置本地窗口缓冲区变换，函数中的可变参数是[输入] int32_t transform，取值具体可见[OH_NativeBuffer_TransformType](capi-native-buffer-h.md#oh_nativebuffer_transformtype)枚举值。 | 115| GET_TRANSFORM | 获取本地窗口缓冲区变换，函数中的可变参数是[输出] int32_t transform，取值具体可见[OH_NativeBuffer_TransformType](capi-native-buffer-h.md#oh_nativebuffer_transformtype)枚举值。 | 116| SET_UI_TIMESTAMP | 设置本地窗口缓冲区UI时间戳，函数中的可变参数是[输入] uint64_t uiTimestamp。 | 117| GET_BUFFERQUEUE_SIZE | 获取内存队列大小，函数中的可变参数是[输出] int32_t \*size。<br/>**起始版本：** 12 | 118| SET_SOURCE_TYPE | 设置本地窗口内容来源，函数中的可变参数是[输入] int32_t sourceType，取值具体可见[OHSurfaceSource](#ohsurfacesource)枚举值。<br/>**起始版本：** 12 | 119| GET_SOURCE_TYPE | 获取本地窗口内容来源，函数中的可变参数是[输出] int32_t *sourceType，取值具体可见[OHSurfaceSource](#ohsurfacesource)枚举值。<br/>**起始版本：** 12 | 120| SET_APP_FRAMEWORK_TYPE | 设置本地窗口应用框架名称，函数中的可变参数是[输入] char* frameworkType，最大支持64字节。<br/>**起始版本：** 12 | 121| GET_APP_FRAMEWORK_TYPE | 获取本地窗口应用框架名称，函数中的可变参数是[输出] char* frameworkType。<br/>**起始版本：** 12 | 122| SET_HDR_WHITE_POINT_BRIGHTNESS | 设置HDR白点亮度，函数中的可变参数是[输入] float brightness。取值范围为[0.0f, 1.0f]。<br/>**起始版本：** 12 | 123| SET_SDR_WHITE_POINT_BRIGHTNESS | 设置SDR白点亮度，函数中的可变参数是[输入] float brightness。取值范围为[0.0f, 1.0f]。<br/>**起始版本：** 12 | 124| SET_DESIRED_PRESENT_TIMESTAMP = 24 | 设置本地窗口缓冲区期望上屏时间的时间戳。<br/> 当且仅当RenderService为本地窗口的消费者时，该时间戳生效<br/>本操作执行后需要配合调用[OH_NativeWindow_NativeWindowFlushBuffer](#oh_nativewindow_nativewindowflushbuffer)生效。<br/>生产者下一次放入队列的buffer，达到该期望上屏时间后，才会被RenderService消费并上屏。<br/>如果buffer队列中存在多个生产者放入的buffer，都设置了desiredPresentTimestamp并已达到期望上屏时间，则较早入队的buffer将被消费者丢弃回队列。<br/>如果期望上屏时间大于消费者提供的时间 1 秒以上，则该期望上屏时间戳将被忽略。<br/> 函数中的可变参数是[输入] int64_t desiredPresentTimestamp，取值范围大于0，应由std::chrono::steady_clock标准库时钟生成，且单位为纳秒。<br/>**起始版本：** 13 | 125 126### OHScalingMode 127 128``` 129enum OHScalingMode 130``` 131 132**描述** 133 134缩放模式Scaling Mode。 135 136**起始版本：** 9 137 138**废弃版本：** 10 139 140**替代接口：** [OHScalingModeV2](#ohscalingmodev2) 141 142| 枚举项 | 描述 | 143| -- | -- | 144| OH_SCALING_MODE_FREEZE = 0 | 在接收到窗口大小的缓冲区之前，不可以更新窗口内容。 | 145| OH_SCALING_MODE_SCALE_TO_WINDOW | 缓冲区在二维中缩放以匹配窗口大小。 | 146| OH_SCALING_MODE_SCALE_CROP | 缓冲区被统一缩放，使得缓冲区的较小尺寸与窗口大小匹配。 | 147| OH_SCALING_MODE_NO_SCALE_CROP | 窗口被裁剪为缓冲区裁剪矩形的大小，裁剪矩形之外的像素被视为完全透明。 | 148 149### OHScalingModeV2 150 151``` 152enum OHScalingModeV2 153``` 154 155**描述** 156 157渲染缩放模式枚举。 158 159**起始版本：** 12 160 161| 枚举项 | 描述 | 162| -- | -- | 163| OH_SCALING_MODE_FREEZE_V2 = 0 | 冻结窗口，在接收到和窗口大小相等的缓冲区之前，窗口内容不进行更新。 | 164| OH_SCALING_MODE_SCALE_TO_WINDOW_V2 | 缓冲区进行拉伸缩放以匹配窗口大小。 | 165| OH_SCALING_MODE_SCALE_CROP_V2 | 缓冲区按原比例缩放，使得缓冲区的较小边与窗口匹配，较长边超出窗口部分被视为透明。 | 166| OH_SCALING_MODE_NO_SCALE_CROP_V2 | 按窗口大小将缓冲区裁剪，裁剪矩形之外的像素被视为完全透明。 | 167| OH_SCALING_MODE_SCALE_FIT_V2 | 缓冲区按原比例缩放。优先显示所有缓冲区内容。如果比例与窗口比例不同，用背景颜色填充窗口的未填充区域。<br><!--Del-->开发板和<!--DelEnd-->模拟器不支持该模式。 | 168 169### OHHDRMetadataKey 170 171``` 172enum OHHDRMetadataKey 173``` 174 175**描述** 176 177枚举HDR元数据关键字。 178 179**起始版本：** 9 180 181**废弃版本：** 10 182 183| 枚举项 | 描述 | 184| -- | -- | 185| OH_METAKEY_RED_PRIMARY_X = 0 | 红基色X坐标。 | 186| OH_METAKEY_RED_PRIMARY_Y = 1, | 红基色Y坐标。 | 187| OH_METAKEY_GREEN_PRIMARY_X = 2, | 绿基色X坐标。 | 188| OH_METAKEY_GREEN_PRIMARY_Y = 3, | 绿基色Y坐标。 | 189| OH_METAKEY_BLUE_PRIMARY_X = 4, | 蓝基色X坐标。 | 190| OH_METAKEY_BLUE_PRIMARY_Y = 5, | 蓝基色Y坐标。 | 191| OH_METAKEY_WHITE_PRIMARY_X = 6, | 白点X坐标。 | 192| OH_METAKEY_WHITE_PRIMARY_Y = 7, | 白点Y坐标。 | 193| OH_METAKEY_MAX_LUMINANCE = 8, | 最大的光亮度。 | 194| OH_METAKEY_MIN_LUMINANCE = 9, | 最小的光亮度。 | 195| OH_METAKEY_MAX_CONTENT_LIGHT_LEVEL = 10, | 最大的内容亮度水平。 | 196| OH_METAKEY_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11, | 最大的帧平均亮度水平。 | 197| OH_METAKEY_HDR10_PLUS = 12, | HDR10 Plus。 | 198| OH_METAKEY_HDR_VIVID = 13, | Vivid。 | 199 200### OHSurfaceSource 201 202``` 203enum OHSurfaceSource 204``` 205 206**描述** 207 208本地窗口内容来源类型枚举。 209 210**起始版本：** 12 211 212| 枚举项 | 描述 | 213| -- | -- | 214| OH_SURFACE_SOURCE_DEFAULT = 0 | 窗口内容默认来源。 | 215| OH_SURFACE_SOURCE_UI | 窗口内容来自于UI。 | 216| OH_SURFACE_SOURCE_GAME | 窗口内容来自于游戏。 | 217| OH_SURFACE_SOURCE_CAMERA | 窗口内容来自于相机。 | 218| OH_SURFACE_SOURCE_VIDEO | 窗口内容来自于视频。 | 219 220 221## 函数说明 222 223### OH_NativeWindow_CreateNativeWindow() 224 225``` 226OHNativeWindow* OH_NativeWindow_CreateNativeWindow(void* pSurface) 227``` 228 229**描述** 230 231创建OHNativeWindow实例，每次调用都会产生一个新的OHNativeWindow实例。<br>说明：此接口不可用，可通过[OH_NativeImage_AcquireNativeWindow](capi-native-image-h.md#oh_nativeimage_acquirenativewindow)创建，或通过XComponent创建。 232 233**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 234 235**起始版本：** 8 236 237**废弃版本：** 从API version 12开始废弃，不再提供替代接口。 238 239**参数：** 240 241| 参数项 | 描述 | 242| -- | -- | 243| void* pSurface | 一个指向生产者ProduceSurface的指针，类型为sptr\<OHOS::Surface>。 | 244 245**返回：** 246 247| 类型 | 说明 | 248| -- | -- | 249| [OHNativeWindow](capi-nativewindow-nativewindow.md)* | 返回一个指针，指向OHNativeWindow的结构体实例。 | 250 251### OH_NativeWindow_DestroyNativeWindow() 252 253``` 254void OH_NativeWindow_DestroyNativeWindow(OHNativeWindow* window) 255``` 256 257**描述** 258 259将OHNativeWindow对象的引用计数减1，当引用计数为0的时候，该OHNativeWindow对象会被析构掉。<br>本接口为非线程安全类型接口。 260 261**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 262 263**起始版本：** 8 264 265 266**参数：** 267 268| 参数项 | 描述 | 269| -- | -- | 270| [OHNativeWindow](capi-nativewindow-nativewindow.md)* window | 一个OHNativeWindow的结构体实例的指针。 | 271 272### OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer() 273 274``` 275OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer(void* pSurfaceBuffer) 276``` 277 278**描述** 279 280创建OHNativeWindowBuffer实例，每次调用都会产生一个新的OHNativeWindowBuffer实例。<br>说明：此接口不可用，使用[OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer](#oh_nativewindow_createnativewindowbufferfromnativebuffer)替代。 281 282**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 283 284**起始版本：** 8 285 286**废弃版本：** 12 287 288**替代接口：** [OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer](#oh_nativewindow_createnativewindowbufferfromnativebuffer) 289 290 291**参数：** 292 293| 参数项 | 描述 | 294| -- | -- | 295| void* pSurfaceBuffer | 一个指向生产者buffer的指针，类型为sptr<OHOS::SurfaceBuffer>。 | 296 297**返回：** 298 299| 类型 | 说明 | 300| -- | -- | 301| OHNativeWindowBuffer* | 返回一个指针，指向OHNativeWindowBuffer的结构体实例。 | 302 303### OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer() 304 305``` 306OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer(OH_NativeBuffer* nativeBuffer) 307``` 308 309**描述** 310 311创建OHNativeWindowBuffer实例，每次调用都会产生一个新的OHNativeWindowBuffer实例。<br>本接口需要与[OH_NativeWindow_DestroyNativeWindowBuffer](#oh_nativewindow_destroynativewindowbuffer)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 312 313**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 314 315**起始版本：** 11 316 317 318**参数：** 319 320| 参数项 | 描述 | 321| -- | -- | 322| OH_NativeBuffer* nativeBuffer | 一个指向OH_NativeBuffer的指针。 | 323 324**返回：** 325 326| 类型 | 说明 | 327| -- | -- | 328| OHNativeWindowBuffer* | 返回一个指针，指向OHNativeWindowBuffer的结构体实例。 | 329 330### OH_NativeWindow_DestroyNativeWindowBuffer() 331 332``` 333void OH_NativeWindow_DestroyNativeWindowBuffer(OHNativeWindowBuffer* buffer) 334``` 335 336**描述** 337 338将OHNativeWindowBuffer对象的引用计数减1，当引用计数为0的时候，该OHNativeWindowBuffer对象会被析构掉。<br>本接口为非线程安全类型接口。 339 340**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 341 342**起始版本：** 8 343 344 345**参数：** 346 347| 参数项 | 描述 | 348| -- | -- | 349| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md)* buffer | 一个OHNativeWindowBuffer的结构体实例的指针。 | 350 351### OH_NativeWindow_NativeWindowRequestBuffer() 352 353``` 354int32_t OH_NativeWindow_NativeWindowRequestBuffer(OHNativeWindow *window,OHNativeWindowBuffer **buffer, int *fenceFd) 355``` 356 357**描述** 358 359通过OHNativeWindow对象申请一块OHNativeWindowBuffer，用以内容生产。<br>在调用本接口前，需要通过[SET_BUFFER_GEOMETRY](#nativewindowoperation)对OHNativeWindow设置宽高。<br>本接口需要与[OH_NativeWindow_NativeWindowFlushBuffer](#oh_nativewindow_nativewindowflushbuffer)接口配合使用，否则内存会耗尽。<br>当fenceFd使用完，用户需要将其close。<br>本接口为非线程安全类型接口。 360 361**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 362 363**起始版本：** 8 364 365 366**参数：** 367 368| 参数项 | 描述 | 369| -- | -- | 370| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 371| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) **buffer | 一个指向OHNativeWindowBuffer指针的指针（二级指针）。<br>通过OH_NativeWindow_GetBufferHandleFromNative可获取BufferHandle结构体，访问缓冲区内存。 | 372| int *fenceFd | 一个文件描述符句柄，用于GPU/CPU同步：不同取值及含义如下：<br>- 返回≥0：缓冲区正被GPU使用，需要等待文件描述符fenceFd就绪。<br>- 返回-1：缓冲区可直接使用。 | 373 374**返回：** 375 376| 类型 | 说明 | 377| -- | -- | 378| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 379 380### OH_NativeWindow_NativeWindowFlushBuffer() 381 382``` 383int32_t OH_NativeWindow_NativeWindowFlushBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer,int fenceFd, Region region) 384``` 385 386**描述** 387 388通过OHNativeWindow将生产好内容的OHNativeWindowBuffer放回到Buffer队列中，用以内容消费。<br>系统会将fenceFd关闭，无需用户close。<br>本接口为非线程安全类型接口。 389 390**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 391 392**起始版本：** 8 393 394 395**参数：** 396 397| 参数项 | 描述 | 398| -- | -- | 399| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 400| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) *buffer | 一个OHNativeWindowBuffer的结构体实例的指针。 | 401| int fenceFd | 一个文件描述符句柄，用以同步时序。不同取值及含义如下：<br>- -1：CPU渲染完成，无需同步时序。<br>- ≥0：从GPU同步对象转换（如EGL的eglDupNativeFenceFDANDROID），对端需要通过此fenceFd同步时序。 | 402| [Region](capi-nativewindow-region.md) region | 一个Region结构体，表示一块脏区域，该区域有内容更新。 | 403 404**返回：** 405 406| 类型 | 说明 | 407| -- | -- | 408| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 409 410### OH_NativeWindow_GetLastFlushedBuffer() 411 412``` 413int32_t OH_NativeWindow_GetLastFlushedBuffer(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16]) 414``` 415 416**描述** 417 418从OHNativeWindow获取上次送回到buffer队列中的OHNativeWindowBuffer。 419 420**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 421 422**起始版本：** 11 423 424**废弃版本：** 从API version 12开始废弃。 425 426**替代接口：** [OH_NativeWindow_GetLastFlushedBufferV2](#oh_nativewindow_getlastflushedbufferv2) 427 428 429**参数：** 430 431| 参数项 | 描述 | 432| -- | -- | 433| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 434| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) **buffer | 一个OHNativeWindowBuffer结构体指针的指针。 | 435| int *fenceFd | 一个文件描述符的指针。 | 436| matrix | 表示检索到的44变换矩阵。 | 437 438**返回：** 439 440| 类型 | 说明 | 441| -- | -- | 442| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 443 444### OH_NativeWindow_NativeWindowAbortBuffer() 445 446``` 447int32_t OH_NativeWindow_NativeWindowAbortBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer) 448``` 449 450**描述** 451 452通过OHNativeWindow将之前申请出来的OHNativeWindowBuffer返还到Buffer队列中，供下次再申请。<br>本接口为非线程安全类型接口。 453 454**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 455 456**起始版本：** 8 457 458 459**参数：** 460 461| 参数项 | 描述 | 462| -- | -- | 463| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 464| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) *buffer | 一个OHNativeWindowBuffer的结构体实例的指针。 | 465 466**返回：** 467 468| 类型 | 说明 | 469| -- | -- | 470| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 471 472### OH_NativeWindow_NativeWindowHandleOpt() 473 474``` 475int32_t OH_NativeWindow_NativeWindowHandleOpt(OHNativeWindow *window, int code, ...) 476``` 477 478**描述** 479 480设置/获取OHNativeWindow的属性，包括设置/获取宽高、内容格式等。<br>本接口为非线程安全类型接口。 481 482**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 483 484**起始版本：** 8 485 486 487**参数：** 488 489| 参数项 | 描述 | 490| -- | -- | 491| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 492| int code | 表示操作码，详见[NativeWindowOperation](#nativewindowoperation)。 | 493| ... | 可变参数，必须与操作码对应的数据类型保持一致，且入参数量严格按照操作码提示传入，否则会存在未定义行为。 | 494 495**返回：** 496 497| 类型 | 说明 | 498| -- | -- | 499| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 500 501### OH_NativeWindow_GetBufferHandleFromNative() 502 503``` 504BufferHandle *OH_NativeWindow_GetBufferHandleFromNative(OHNativeWindowBuffer *buffer) 505``` 506 507**描述** 508 509通过OHNativeWindowBuffer获取该buffer的BufferHandle指针。<br>本接口为非线程安全类型接口。 510 511**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 512 513**起始版本：** 8 514 515 516**参数：** 517 518| 参数项 | 描述 | 519| -- | -- | 520| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) *buffer | 一个OHNativeWindowBuffer的结构体实例的指针。 | 521 522**返回：** 523 524| 类型 | 说明 | 525| -- | -- | 526| [BufferHandle](capi-nativewindow-bufferhandle.md) | BufferHandle 返回一个指针，指向[BufferHandle](capi-nativewindow-bufferhandle.md)的结构体实例。 | 527 528### OH_NativeWindow_NativeObjectReference() 529 530``` 531int32_t OH_NativeWindow_NativeObjectReference(void *obj) 532``` 533 534**描述** 535 536增加一个NativeObject的引用计数。<br>本接口需要与[OH_NativeWindow_NativeObjectUnreference](#oh_nativewindow_nativeobjectunreference)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 537 538**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 539 540**起始版本：** 8 541 542 543**参数：** 544 545| 参数项 | 描述 | 546| -- | -- | 547| void *obj | 一个OHNativeWindow或者OHNativeWindowBuffer的结构体实例的指针。 | 548 549**返回：** 550 551| 类型 | 说明 | 552| -- | -- | 553| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 554 555### OH_NativeWindow_NativeObjectUnreference() 556 557``` 558int32_t OH_NativeWindow_NativeObjectUnreference(void *obj) 559``` 560 561**描述** 562 563减少一个NativeObject的引用计数，当引用计数减少为0时，该NativeObject将被析构掉。<br>本接口为非线程安全类型接口。 564 565**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 566 567**起始版本：** 8 568 569 570**参数：** 571 572| 参数项 | 描述 | 573| -- | -- | 574| void *obj | 一个OHNativeWindow或者OHNativeWindowBuffer的结构体实例的指针。 | 575 576**返回：** 577 578| 类型 | 说明 | 579| -- | -- | 580| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 581 582### OH_NativeWindow_GetNativeObjectMagic() 583 584``` 585int32_t OH_NativeWindow_GetNativeObjectMagic(void *obj) 586``` 587 588**描述** 589 590获取NativeObject的MagicId。<br>本接口为非线程安全类型接口。 591 592**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 593 594**起始版本：** 8 595 596 597**参数：** 598 599| 参数项 | 描述 | 600| -- | -- | 601| void *obj | 一个OHNativeWindow或者OHNativeWindowBuffer的结构体实例的指针。 | 602 603**返回：** 604 605| 类型 | 说明 | 606| -- | -- | 607| int32_t | MagicId 返回值为魔鬼数字，每个NativeObject唯一。 | 608 609### OH_NativeWindow_NativeWindowSetScalingMode() 610 611``` 612int32_t OH_NativeWindow_NativeWindowSetScalingMode(OHNativeWindow *window, uint32_t sequence,OHScalingMode scalingMode) 613``` 614 615**描述** 616 617设置OHNativeWindow的ScalingMode。 618 619**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 620 621**起始版本：** 9 622 623**废弃版本：** 从API version 10开始废弃。 624 625**替代接口：** [OH_NativeWindow_NativeWindowSetScalingModeV2](#oh_nativewindow_nativewindowsetscalingmodev2) 626 627 628**参数：** 629 630| 参数项 | 描述 | 631| -- | -- | 632| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 633| uint32_t sequence | 生产缓冲区的序列。 | 634| [OHScalingMode](#ohscalingmode) scalingMode | 枚举值OHScalingMode。 | 635 636**返回：** 637 638| 类型 | 说明 | 639| -- | -- | 640| int32_t | 返回值为0表示执行成功。 | 641 642### OH_NativeWindow_NativeWindowSetMetaData() 643 644``` 645int32_t OH_NativeWindow_NativeWindowSetMetaData(OHNativeWindow *window, uint32_t sequence, int32_t size,const OHHDRMetaData *metaData) 646``` 647 648**描述** 649 650设置OHNativeWindow的元数据。 651 652**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 653 654**起始版本：** 9 655 656**废弃版本：** 从API version 10开始废弃，不再提供替代接口。 657 658 659**参数：** 660 661| 参数项 | 描述 | 662| -- | -- | 663| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 664| uint32_t sequence | 生产缓冲区的序列。 | 665| int32_t size | OHHDRMetaData数组的大小。 | 666| metaData | 指向OHHDRMetaData数组的指针。 | 667 668**返回：** 669 670| 类型 | 说明 | 671| -- | -- | 672| int32_t | 返回值为0表示执行成功。 | 673 674### OH_NativeWindow_NativeWindowSetMetaDataSet() 675 676``` 677int32_t OH_NativeWindow_NativeWindowSetMetaDataSet(OHNativeWindow *window, uint32_t sequence, OHHDRMetadataKey key,int32_t size, const uint8_t *metaData) 678``` 679 680**描述** 681 682设置OHNativeWindow的元数据集。 683 684**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 685 686**起始版本：** 9 687 688**废弃版本：** 从API version 10开始废弃，不再提供替代接口。 689 690 691**参数：** 692 693| 参数项 | 描述 | 694| -- | -- | 695| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 696| uint32_t sequence | 生产缓冲区的序列。 | 697| [OHHDRMetadataKey](#ohhdrmetadatakey) key | 枚举值OHHDRMetadataKey。 | 698| int32_t size | uint8_t向量的大小。 | 699| metaDate | 指向uint8_t向量的指针。 | 700 701**返回：** 702 703| 类型 | 说明 | 704| -- | -- | 705| int32_t | 返回值为0表示执行成功。 | 706 707### OH_NativeWindow_NativeWindowSetTunnelHandle() 708 709``` 710int32_t OH_NativeWindow_NativeWindowSetTunnelHandle(OHNativeWindow *window, const OHExtDataHandle *handle) 711``` 712 713**描述** 714 715设置OHNativeWindow的TunnelHandle。 716 717**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 718 719**起始版本：** 9 720 721**废弃版本：** 从API version 10开始废弃，不再提供替代接口。 722 723 724**参数：** 725 726| 参数项 | 描述 | 727| -- | -- | 728| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 729| const [OHExtDataHandle](capi-nativewindow-ohextdatahandle.md) *handle | 指向OHExtDataHandle的指针。 | 730 731**返回：** 732 733| 类型 | 说明 | 734| -- | -- | 735| int32_t | 返回值为0表示执行成功。 | 736 737### OH_NativeWindow_NativeWindowAttachBuffer() 738 739``` 740int32_t OH_NativeWindow_NativeWindowAttachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer) 741``` 742 743**描述** 744 745将OHNativeWindowBuffer添加进OHNativeWindow中。<br>本接口需要与[OH_NativeWindow_NativeWindowDetachBuffer](#oh_nativewindow_nativewindowdetachbuffer)接口配合使用，否则会存在内存管理混乱问题。<br>本接口为非线程安全类型接口。<br> 746 747**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 748 749**起始版本：** 12 750 751 752**参数：** 753 754| 参数项 | 描述 | 755| -- | -- | 756| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 757| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) *buffer | 一个OHNativeWindowBuffer的结构体实例的指针。 | 758 759**返回：** 760 761| 类型 | 说明 | 762| -- | -- | 763| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 764 765### OH_NativeWindow_NativeWindowDetachBuffer() 766 767``` 768int32_t OH_NativeWindow_NativeWindowDetachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer) 769``` 770 771**描述** 772 773将OHNativeWindowBuffer从OHNativeWindow中分离。<br>本接口为非线程安全类型接口。 774 775**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 776 777**起始版本：** 12 778 779 780**参数：** 781 782| 参数项 | 描述 | 783| -- | -- | 784| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 785| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) *buffer | 一个OHNativeWindowBuffer的结构体实例的指针。 | 786 787**返回：** 788 789| 类型 | 说明 | 790| -- | -- | 791| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 792 793### OH_NativeWindow_GetSurfaceId() 794 795``` 796int32_t OH_NativeWindow_GetSurfaceId(OHNativeWindow *window, uint64_t *surfaceId) 797``` 798 799**描述** 800 801通过OHNativeWindow获取对应的surfaceId。<br>本接口为非线程安全类型接口。 802 803**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 804 805**起始版本：** 12 806 807 808**参数：** 809 810| 参数项 | 描述 | 811| -- | -- | 812| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 813| uint64_t *surfaceId | 一个surface对应ID的指针。 | 814 815**返回：** 816 817| 类型 | 说明 | 818| -- | -- | 819| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 820 821### OH_NativeWindow_CreateNativeWindowFromSurfaceId() 822 823``` 824int32_t OH_NativeWindow_CreateNativeWindowFromSurfaceId(uint64_t surfaceId, OHNativeWindow **window) 825``` 826 827**描述** 828 829通过surfaceId创建对应的OHNativeWindow。<br>本接口需要与[OH_NativeWindow_DestroyNativeWindow](#oh_nativewindow_destroynativewindow)接口配合使用，否则会存在内存泄露。<br>如果存在并发释放OHNativeWindow的情况，需要通过[OH_NativeWindow_NativeObjectReference](#oh_nativewindow_nativeobjectreference)和[OH_NativeWindow_NativeObjectUnreference](#oh_nativewindow_nativeobjectunreference)对OHNativeWindow进行引用计数加一和减一。<br>通过surfaceId获取的surface需要是在本进程中创建的，不能跨进程获取surface。<br>本接口为非线程安全类型接口。 830 831**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 832 833**起始版本：** 12 834 835 836**参数：** 837 838| 参数项 | 描述 | 839| -- | -- | 840| uint64_t surfaceId | 一个surface对应的ID。 | 841| [OHNativeWindow](capi-nativewindow-nativewindow.md) **window | 一个OHNativeWindow的结构体实例的二级指针。 | 842 843**返回：** 844 845| 类型 | 说明 | 846| -- | -- | 847| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 848 849### OH_NativeWindow_NativeWindowSetScalingModeV2() 850 851``` 852int32_t OH_NativeWindow_NativeWindowSetScalingModeV2(OHNativeWindow* window, OHScalingModeV2 scalingMode) 853``` 854 855**描述** 856 857设置OHNativeWindow的渲染缩放模式。<br>本接口为非线程安全类型接口。 858 859**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 860 861**起始版本：** 12 862 863 864**参数：** 865 866| 参数项 | 描述 | 867| -- | -- | 868| [OHNativeWindow](capi-nativewindow-nativewindow.md)* window | 一个OHNativeWindow的结构体实例的指针。 | 869| [OHScalingModeV2](#ohscalingmodev2) scalingMode | 一个OHScalingModeV2类型的枚举值。 | 870 871**返回：** 872 873| 类型 | 说明 | 874| -- | -- | 875| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 876 877### OH_NativeWindow_GetLastFlushedBufferV2() 878 879``` 880int32_t OH_NativeWindow_GetLastFlushedBufferV2(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16]) 881``` 882 883**描述** 884 885从OHNativeWindow获取上次送回到buffer队列中的OHNativeWindowBuffer,与OH_NativeWindow_GetLastFlushedBuffer的差异在于matrix不同。<br>本接口需要与[OH_NativeWindow_NativeObjectUnreference](#oh_nativewindow_nativeobjectunreference)接口配合使用，否则会存在内存泄露。<br>本接口为非线程安全类型接口。 886 887**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 888 889**起始版本：** 12 890 891 892**参数：** 893 894| 参数项 | 描述 | 895| -- | -- | 896| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个OHNativeWindow的结构体实例的指针。 | 897| [OHNativeWindowBuffer](capi-nativewindow-nativewindowbuffer.md) **buffer | 一个OHNativeWindowBuffer结构体指针的指针。 | 898| int *fenceFd | 一个文件描述符的指针。 | 899| matrix | 表示检索到的44变换矩阵。 | 900 901**返回：** 902 903| 类型 | 说明 | 904| -- | -- | 905| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 906 907### OH_NativeWindow_SetBufferHold() 908 909``` 910void OH_NativeWindow_SetBufferHold(OHNativeWindow *window) 911``` 912 913**描述** 914 915提前缓存一帧buffer，且缓存的这一帧延迟一帧上屏显示，以此抵消后续一次超长帧丢帧。<br>本接口为非线程安全类型接口。 916 917**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 918 919**起始版本：** 12 920 921 922**参数：** 923 924| 参数项 | 描述 | 925| -- | -- | 926| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的指针。 | 927 928### OH_NativeWindow_WriteToParcel() 929 930``` 931int32_t OH_NativeWindow_WriteToParcel(OHNativeWindow *window, OHIPCParcel *parcel) 932``` 933 934**描述** 935 936将窗口对象写入IPC序列化对象中。<br>本接口为非线程安全类型接口。 937 938**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 939 940**起始版本：** 12 941 942 943**参数：** 944 945| 参数项 | 描述 | 946| -- | -- | 947| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个指向[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的指针。 | 948| [OHIPCParcel](capi-nativewindow-ohipcparcel.md) *parcel | 一个指向[OHIPCParcel](capi-nativewindow-ohipcparcel.md)的结构体实例的指针。 | 949 950**返回：** 951 952| 类型 | 说明 | 953| -- | -- | 954| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 955 956### OH_NativeWindow_ReadFromParcel() 957 958``` 959int32_t OH_NativeWindow_ReadFromParcel(OHIPCParcel *parcel, OHNativeWindow **window) 960``` 961 962**描述** 963 964从IPC序列化对象中读取窗口对象。<br>本接口为非线程安全类型接口。 965 966**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 967 968**起始版本：** 12 969 970 971**参数：** 972 973| 参数项 | 描述 | 974| -- | -- | 975| [OHIPCParcel](capi-nativewindow-ohipcparcel.md) *parcel | 一个指向[OHIPCParcel](capi-nativewindow-ohipcparcel.md)的结构体实例的指针。 | 976| [OHNativeWindow](capi-nativewindow-nativewindow.md) **window | 一个指向[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的二级指针。 | 977 978**返回：** 979 980| 类型 | 说明 | 981| -- | -- | 982| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 983 984### OH_NativeWindow_SetColorSpace() 985 986``` 987int32_t OH_NativeWindow_SetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace colorSpace) 988``` 989 990**描述** 991 992为OHNativeWindow设置颜色空间属性。<br>本接口为非线程安全类型接口。 993 994**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 995 996**起始版本：** 12 997 998 999**参数：** 1000 1001| 参数项 | 描述 | 1002| -- | -- | 1003| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个指向[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的指针。 | 1004| [OH_NativeBuffer_ColorSpace](capi-buffer-common-h.md#oh_nativebuffer_colorspace) colorSpace | 为OHNativeWindow设置的颜色空间，其值从[OH_NativeBuffer_ColorSpace](capi-buffer-common-h.md#oh_nativebuffer_colorspace)获取。 | 1005 1006**返回：** 1007 1008| 类型 | 说明 | 1009| -- | -- | 1010| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 1011 1012### OH_NativeWindow_GetColorSpace() 1013 1014``` 1015int32_t OH_NativeWindow_GetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace *colorSpace) 1016``` 1017 1018**描述** 1019 1020获取OHNativeWindow颜色空间属性。<br>本接口为非线程安全类型接口。 1021 1022**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 1023 1024**起始版本：** 12 1025 1026 1027**参数：** 1028 1029| 参数项 | 描述 | 1030| -- | -- | 1031| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个指向[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的指针。 | 1032| [OH_NativeBuffer_ColorSpace](capi-buffer-common-h.md#oh_nativebuffer_colorspace) *colorSpace | 为OHNativeWindow设置的颜色空间，其值从[OH_NativeBuffer_ColorSpace](capi-buffer-common-h.md#oh_nativebuffer_colorspace)获取。 | 1033 1034**返回：** 1035 1036| 类型 | 说明 | 1037| -- | -- | 1038| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 1039 1040### OH_NativeWindow_SetMetadataValue() 1041 1042``` 1043int32_t OH_NativeWindow_SetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t size, uint8_t *metadata) 1044``` 1045 1046**描述** 1047 1048为OHNativeWindow设置元数据属性值。<br>本接口为非线程安全类型接口。 1049 1050**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 1051 1052**起始版本：** 12 1053 1054 1055**参数：** 1056 1057| 参数项 | 描述 | 1058| -- | -- | 1059| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个指向[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的指针。 | 1060| [OH_NativeBuffer_MetadataKey](capi-buffer-common-h.md#oh_nativebuffer_metadatakey) metadataKey | Window的元数据类型，其值从[OH_NativeBuffer_MetadataKey](capi-buffer-common-h.md#oh_nativebuffer_metadatakey)获取。 | 1061| int32_t size | uint8_t向量的大小，其取值范围见[OH_NativeBuffer_MetadataKey](capi-buffer-common-h.md#oh_nativebuffer_metadatakey)。 | 1062| metaDate | 指向uint8_t向量的指针。 | 1063 1064**返回：** 1065 1066| 类型 | 说明 | 1067| -- | -- | 1068| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 1069 1070### OH_NativeWindow_GetMetadataValue() 1071 1072``` 1073int32_t OH_NativeWindow_GetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t *size, uint8_t **metadata) 1074``` 1075 1076**描述** 1077 1078获取OHNativeWindow元数据属性值。<br>本接口为非线程安全类型接口。 1079 1080**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 1081 1082**起始版本：** 12 1083 1084 1085**参数：** 1086 1087| 参数项 | 描述 | 1088| -- | -- | 1089| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个指向[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的指针。 | 1090| [OH_NativeBuffer_MetadataKey](capi-buffer-common-h.md#oh_nativebuffer_metadatakey) metadataKey | Window的元数据类型，其值从[OH_NativeBuffer_MetadataKey](capi-buffer-common-h.md#oh_nativebuffer_metadatakey)获取。 | 1091| int32_t *size | uint8_t向量的大小，其取值范围见[OH_NativeBuffer_MetadataKey](capi-buffer-common-h.md#oh_nativebuffer_metadatakey)。 | 1092| metaDate | 指向uint8_t向量的二级指针。 | 1093 1094**返回：** 1095 1096| 类型 | 说明 | 1097| -- | -- | 1098| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 1099 1100### OH_NativeWindow_CleanCache() 1101 1102``` 1103int32_t OH_NativeWindow_CleanCache(OHNativeWindow *window) 1104``` 1105 1106**描述** 1107 1108清理OHNativeWindow中的OHNativeWindowBuffer缓存。<br>使用该接口清理缓存前，需确保已通过[OH_NativeWindow_NativeWindowRequestBuffer](#oh_nativewindow_nativewindowrequestbuffer)接口成功申请OHNativeWindowBuffer。<br>本接口为非线程安全类型接口。 1109 1110**系统能力：** SystemCapability.Graphic.Graphic2D.NativeWindow 1111 1112**起始版本：** 19 1113 1114 1115**参数：** 1116 1117| 参数项 | 描述 | 1118| -- | -- | 1119| [OHNativeWindow](capi-nativewindow-nativewindow.md) *window | 一个指向[OHNativeWindow](capi-nativewindow-nativewindow.md)的结构体实例的指针。 | 1120 1121**返回：** 1122 1123| 类型 | 说明 | 1124| -- | -- | 1125| int32_t | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 1126 1127 1128