1# NativeWindow开发指导 (C/C++) 2 3## 场景介绍 4 5NativeWindow是**本地平台化窗口**，表示图形队列的生产者端。开发者可以通过`NativeWindow`接口进行申请和提交`Buffer`，配置`Buffer`属性信息。 6针对NativeWindow，常见的开发场景如下： 7 8* 通过`NativeWindow`提供的Native API接口申请图形`Buffer`，并将生产图形内容写入图形`Buffer`，最终提交`Buffer`到图形队列 9* 在适配EGL层的`eglswapbuffer`接口时，进行申请和提交`Buffer` 10 11## 接口说明 12 13| 接口名 | 描述 | 14| -------- | -------- | 15| OH_NativeWindow_NativeWindowRequestBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*\*buffer, int \*fenceFd) | 通过OHNativeWindow对象申请一块OHNativeWindowBuffer，用以内容生产。 | 16| OH_NativeWindow_NativeWindowFlushBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*buffer, int fenceFd, Region region) | 通过OHNativeWindow将生产好内容的OHNativeWindowBuffer放回到Buffer队列中，用以内容消费。 | 17| OH_NativeWindow_NativeWindowHandleOpt (OHNativeWindow \*window, int code,...) | 设置/获取OHNativeWindow的属性，包括设置/获取宽高、内容格式等。 | 18 19详细的接口说明请参考[native_window](../reference/apis-arkgraphics2d/_native_window.md)。 20 21## 开发步骤 22 23以下步骤描述了如何使用`NativeWindow`提供的Native API接口，申请图形`Buffer`，并将生产图形内容写入图形`Buffer`后，最终提交`Buffer`到图形队列。 24 25**添加动态链接库** 26 27CMakeLists.txt中添加以下lib。 28```txt 29libace_ndk.z.so 30libnative_window.so 31``` 32 33**头文件** 34```c++ 35#include <ace/xcomponent/native_interface_xcomponent.h> 36#include <native_window/external_window.h> 37``` 38 391. **获取OHNativeWindow实例**。 40 41 可在[OH_NativeXComponent_Callback](../reference/apis-arkui/_o_h___native_x_component___callback.md)提供的接口中获取OHNativeWindow，下面提供一份代码示例。XComponent模块的具体使用方法请参考[XComponent开发指导](../ui/napi-xcomponent-guidelines.md)。 42 1. 在xxx.ets中添加一个XComponent组件。 43 ```ts 44 XComponent({ id: 'xcomponentId', type: 'surface', libraryname: 'entry'}) 45 .width(360) 46 .height(360) 47 ``` 48 2. 在 native c++ 层获取 NativeXComponent。 49 ```c++ 50 napi_value exportInstance = nullptr; 51 // 用来解析出被wrap了NativeXComponent指针的属性 52 napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance); 53 OH_NativeXComponent *nativeXComponent = nullptr; 54 // 通过napi_unwrap接口，解析出NativeXComponent的实例指针 55 napi_unwrap(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent)); 56 // 获取XComponentId 57 char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {}; 58 uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1; 59 OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize); 60 ``` 61 3. 定义 OH_NativeXComponent_Callback。 62 ```c++ 63 // 定义回调函数 64 void OnSurfaceCreatedCB(OH_NativeXComponent* component, void* window) 65 { 66 // 可获取 OHNativeWindow 实例 67 OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window); 68 // ... 69 } 70 void OnSurfaceChangedCB(OH_NativeXComponent* component, void* window) 71 { 72 // 可获取 OHNativeWindow 实例 73 OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window); 74 // ... 75 } 76 void OnSurfaceDestroyedCB(OH_NativeXComponent* component, void* window) 77 { 78 // 可获取 OHNativeWindow 实例 79 OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window); 80 // ... 81 } 82 void DispatchTouchEventCB(OH_NativeXComponent* component, void* window) 83 { 84 // 可获取 OHNativeWindow 实例 85 OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window); 86 // ... 87 } 88 ``` 89 ```c++ 90 // 初始化 OH_NativeXComponent_Callback 91 OH_NativeXComponent_Callback callback; 92 callback.OnSurfaceCreated = OnSurfaceCreatedCB; 93 callback.OnSurfaceChanged = OnSurfaceChangedCB; 94 callback.OnSurfaceDestroyed = OnSurfaceDestroyedCB; 95 callback.DispatchTouchEvent = DispatchTouchEventCB; 96 ``` 97 4. 将 OH_NativeXComponent_Callback 注册给 NativeXComponent。 98 ```c++ 99 // 注册回调函数 100 OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback); 101 ``` 102 1032. **设置OHNativeWindowBuffer的属性**。使用`OH_NativeWindow_NativeWindowHandleOpt`设置`OHNativeWindowBuffer`的属性。 104 ```c++ 105 // 设置 OHNativeWindowBuffer 的宽高 106 int32_t code = SET_BUFFER_GEOMETRY; 107 int32_t width = 0x100; 108 int32_t height = 0x100; 109 // 这里的nativeWindow是从上一步骤中的回调函数中获得的 110 int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height); 111 ``` 112 1133. **从图形队列申请OHNativeWindowBuffer**。 114 ```c++ 115 OHNativeWindowBuffer* buffer = nullptr; 116 int fenceFd; 117 // 通过 OH_NativeWindow_NativeWindowRequestBuffer 获取 OHNativeWindowBuffer 实例 118 OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow, &buffer, &fenceFd); 119 // 通过 OH_NativeWindow_GetBufferHandleFromNative 获取 buffer 的 handle 120 BufferHandle* bufferHandle = OH_NativeWindow_GetBufferHandleFromNative(buffer); 121 ``` 122 1234. **内存映射mmap**。 124 ```c++ 125 #include <sys/mman.h> 126 127 // 使用内存映射函数mmap将bufferHandle对应的共享内存映射到用户空间，可以通过映射出来的虚拟地址向bufferHandle中写入图像数据 128 // bufferHandle->virAddr是bufferHandle在共享内存中的起始地址，bufferHandle->size是bufferHandle在共享内存中的内存占用大小 129 void* mappedAddr = mmap(bufferHandle->virAddr, bufferHandle->size, PROT_READ | PROT_WRITE, MAP_SHARED, bufferHandle->fd, 0); 130 if (mappedAddr == MAP_FAILED) { 131 // mmap failed 132 } 133 ``` 134 1355. **将生产的内容写入OHNativeWindowBuffer**。 136 ```c++ 137 static uint32_t value = 0x00; 138 value++; 139 uint32_t *pixel = static_cast<uint32_t *>(mappedAddr); // 使用mmap获取到的地址来访问内存 140 for (uint32_t x = 0; x < width; x++) { 141 for (uint32_t y = 0; y < height; y++) { 142 *pixel++ = value; 143 } 144 } 145 ``` 146 1475. **提交OHNativeWindowBuffer到图形队列**。 148 ```c++ 149 // 设置刷新区域，如果Region中的Rect为nullptr,或者rectNumber为0，则认为OHNativeWindowBuffer全部有内容更改。 150 Region region{nullptr, 0}; 151 // 通过OH_NativeWindow_NativeWindowFlushBuffer 提交给消费者使用，例如：显示在屏幕上。 152 OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow, buffer, fenceFd, region); 153 ``` 1546. **取消内存映射munmap**。 155 ```c++ 156 // 内存使用完记得去掉内存映射 157 int result = munmap(mappedAddr, bufferHandle->size); 158 if (result == -1) { 159 // munmap failed 160 } 161 ``` 162 163## 相关实例 164 165针对NativeWindow的开发，有以下相关实例可供参考： 166 167- [NativeWindow（API11）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Native/NdkNativeWindow)