• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# NativeWindow开发指导 (C/C++)
2<!--Kit: ArkGraphics 2D-->
3<!--Subsystem: Graphics-->
4<!--Owner: @Felix-fangyang; @li_hui180; @dingpy-->
5<!--Designer: @conan13234-->
6<!--Tester: @nobuggers-->
7<!--Adviser: @ge-yafang-->
8## 场景介绍
9
10NativeWindow是**本地平台化窗口**，表示图形队列的生产者端。开发者可以通过`NativeWindow`接口进行申请和提交`Buffer`，配置`Buffer`属性信息。
11针对NativeWindow，常见的开发场景如下：
12
13* 通过`NativeWindow`提供的Native API接口申请图形`Buffer`，并将生产图形内容写入图形`Buffer`，最终提交`Buffer`到图形队列。
14* 在适配EGL层的`eglswapbuffer`接口时，进行申请和提交`Buffer`。
15
16## 接口说明
17
18| 接口名 | 描述 |
19| -------- | -------- |
20| OH_NativeWindow_NativeWindowRequestBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*\*buffer, int \*fenceFd) | 通过OHNativeWindow对象申请一块OHNativeWindowBuffer，用以内容生产。 |
21| OH_NativeWindow_NativeWindowFlushBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*buffer, int fenceFd, Region region) | 通过OHNativeWindow将生产好内容的OHNativeWindowBuffer放回到Buffer队列中，用以内容消费。 |
22| OH_NativeWindow_NativeWindowHandleOpt (OHNativeWindow \*window, int code,...) | 设置/获取OHNativeWindow的属性，包括设置/获取宽高、内容格式等。 |
23
24详细的接口说明请参考[native_window](../reference/apis-arkgraphics2d/capi-nativewindow.md)。
25
26## 开发步骤
27
28以下步骤描述了如何使用`NativeWindow`提供的Native API接口，申请图形`Buffer`，并将生产图形内容写入图形`Buffer`后，最终提交`Buffer`到图形队列。
29
30**添加动态链接库**
31
32CMakeLists.txt中添加以下lib。
33```txt
34libace_ndk.z.so
35libnative_window.so
36```
37
38**头文件**
39```c++
40#include <sys/poll.h>
41#include <sys/mman.h>
42#include <unistd.h>
43#include <ace/xcomponent/native_interface_xcomponent.h>
44#include <native_window/external_window.h>
45```
46
471. 获取OHNativeWindow实例。
48
49    可在[`OH_NativeXComponent_Callback`](../reference/apis-arkui/capi-oh-nativexcomponent-native-xcomponent-oh-nativexcomponent-callback.md)提供的接口中获取OHNativeWindow，下面提供一份代码示例。XComponent模块的具体使用方法请参考[XComponent开发指导](../ui/napi-xcomponent-guidelines.md)。
50
51    1. 在xxx.ets中添加一个XComponent组件。
52
53        ```ts
54        XComponent({ id: 'xcomponentId', type: XComponentType.SURFACE, libraryname: 'entry'})
55            .width(360)
56            .height(360)
57        ```
58    2. 在 native c++ 层获取 NativeXComponent。
59
60        ```c++
61        napi_value exportInstance = nullptr;
62        // 用来解析出被wrap了NativeXComponent指针的属性
63        napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
64        OH_NativeXComponent *nativeXComponent = nullptr;
65        // 通过napi_unwrap接口，解析出NativeXComponent的实例指针
66        napi_unwrap(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent));
67        // 获取XComponentId
68        char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {};
69        uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
70        OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize);
71        ```
72    3. 定义 OH_NativeXComponent_Callback。
73
74        ```c++
75        // 定义回调函数
76        void OnSurfaceCreatedCB(OH_NativeXComponent* component, void* window)
77        {
78            // 可获取 OHNativeWindow 实例
79            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
80            // 此回调触发后，window默认引用计数会设置为1，若存在并发使用了window相关的接口和xcomponent析构的情况，
81            // 则需要通过OH_NativeWindow_NativeObjectReference和OH_NativeWindow_NativeObjectUnreference对window进行
82            // 手动引用计数加1和减1，防止xcomponent析构后，并发调用window相关接口触发野指针或空指针的崩溃。
83        }
84        void OnSurfaceChangedCB(OH_NativeXComponent* component, void* window)
85        {
86            // 可获取 OHNativeWindow 实例
87            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
88            // ...
89        }
90        void OnSurfaceDestroyedCB(OH_NativeXComponent* component, void* window)
91        {
92            // 可获取 OHNativeWindow 实例
93            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
94            // 此回调触发后，会将window进行引用计数减1的操作，当window的应用计数为0后，会触发window的析构，
95            // window析构后，不可再通过window进行接口调用，否则可能会触发野指针或空指针的崩溃。
96        }
97        void DispatchTouchEventCB(OH_NativeXComponent* component, void* window)
98        {
99            // 可获取 OHNativeWindow 实例
100            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
101            // ...
102        }
103        ```
104
105        ```c++
106        // 初始化 OH_NativeXComponent_Callback
107        OH_NativeXComponent_Callback callback;
108        callback.OnSurfaceCreated = OnSurfaceCreatedCB;
109        callback.OnSurfaceChanged = OnSurfaceChangedCB;
110        callback.OnSurfaceDestroyed = OnSurfaceDestroyedCB;
111        callback.DispatchTouchEvent = DispatchTouchEventCB;
112        ```
113
114   4. 将OH_NativeXComponent_Callback 注册给 NativeXComponent。
115
116        ```c++
117        // 注册回调函数
118        OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback);
119        ```
120
1212. 设置OHNativeWindowBuffer的属性。使用`OH_NativeWindow_NativeWindowHandleOpt`设置`OHNativeWindowBuffer`的属性。
122
123    ```c++
124    // 设置 OHNativeWindowBuffer 的宽高
125    int32_t code = SET_BUFFER_GEOMETRY;
126    int32_t width = 0x100;
127    int32_t height = 0x100;
128    // 这里的nativeWindow是从上一步骤中的回调函数中获得的
129    int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height);
130    ```
131
1323. 从图形队列申请OHNativeWindowBuffer。
133
134    ```c++
135    OHNativeWindowBuffer* buffer = nullptr;
136    int releaseFenceFd = -1;
137    // 通过 OH_NativeWindow_NativeWindowRequestBuffer 获取 OHNativeWindowBuffer 实例
138    ret = OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow, &buffer, &releaseFenceFd);
139    if (ret != 0 || buffer == nullptr) {
140        return;
141    }
142    // 通过 OH_NativeWindow_GetBufferHandleFromNative 获取 buffer 的 handle
143    BufferHandle* bufferHandle = OH_NativeWindow_GetBufferHandleFromNative(buffer);
144    ```
145
1464. 内存映射mmap。
147
148    ```c++
149    #include <sys/mman.h>
150
151    // 使用内存映射函数mmap将bufferHandle对应的共享内存映射到用户空间，可以通过映射出来的虚拟地址向bufferHandle中写入图像数据
152    // bufferHandle->virAddr是bufferHandle在共享内存中的起始地址，bufferHandle->size是bufferHandle在共享内存中的内存占用大小
153    void* mappedAddr = mmap(bufferHandle->virAddr, bufferHandle->size, PROT_READ | PROT_WRITE, MAP_SHARED, bufferHandle->fd, 0);
154    if (mappedAddr == MAP_FAILED) {
155        // mmap failed
156    }
157    ```
158
1595. 将生产的内容写入OHNativeWindowBuffer，在这之前需要等待releaseFenceFd可用（注意releaseFenceFd不等于-1才需要调用poll）。如果没有等待releaseFenceFd事件的数据可用（POLLIN），则可能造成花屏、裂屏、HEBC（High Efficiency Bandwidth Compression，高效带宽压缩） fault等问题。releaseFenceFd是消费者进程创建的一个文件句柄，代表消费者消费buffer完毕，buffer可读，生产者可以开始填充buffer内容。
160
161    ```c++
162    int retCode = -1;
163    uint32_t timeout = 3000;
164    if (releaseFenceFd != -1) {
165        struct pollfd pollfds = {0};
166        pollfds.fd = releaseFenceFd;
167        pollfds.events = POLLIN;
168        do {
169            retCode = poll(&pollfds, 1, timeout);
170        } while (retCode == -1 && (errno == EINTR || errno == EAGAIN));
171        close(releaseFenceFd); // 防止fd泄漏
172    }
173
174    static uint32_t value = 0x00;
175    value++;
176    uint32_t *pixel = static_cast<uint32_t *>(mappedAddr); // 使用mmap获取到的地址来访问内存
177    for (uint32_t x = 0; x < width; x++) {
178        for (uint32_t y = 0;  y < height; y++) {
179            *pixel++ = value;
180        }
181    }
182    ```
183
1846. 提交OHNativeWindowBuffer到图形队列。请注意OH_NativeWindow_NativeWindowFlushBuffer接口的acquireFenceFd不可以和OH_NativeWindow_NativeWindowRequestBuffer接口获取的releaseFenceFd相同，acquireFenceFd可传入默认值-1。acquireFenceFd是生产者需要传入的文件句柄，消费者获取到buffer后可根据生产者传入的acquireFenceFd决定何时去渲染并上屏buffer内容。
185
186    ```c++
187    // 设置刷新区域，如果Region中的Rect为nullptr,或者rectNumber为0，则认为OHNativeWindowBuffer全部有内容更改。
188    Region region{nullptr, 0};
189    int acquireFenceFd = -1;
190    // 通过OH_NativeWindow_NativeWindowFlushBuffer 提交给消费者使用，例如：显示在屏幕上。
191    OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow, buffer, acquireFenceFd, region);
192    ```
193
1947. 取消内存映射munmap。
195
196    ```c++
197    // 内存使用完记得去掉内存映射
198    int result = munmap(mappedAddr, bufferHandle->size);
199    if (result == -1) {
200        // munmap failed
201    }
202    ```
203
204## 相关实例
205
206针对NativeWindow的开发，有以下相关实例可供参考：
207
208- [NativeWindow（API11）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Native/NdkNativeWindow)