• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# NativeWindow开发指导
2
3## 场景介绍
4
5NativeWindow是`OpenHarmony`**本地平台化窗口**，表示图形队列的生产者端。开发者可以通过`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/native-apis/_native_window.md)。
20
21## 开发步骤
22
23以下步骤描述了在**OpenHarmony**中如何使用`NativeWindow`提供的Native API接口，申请图形`Buffer`，并将生产图形内容写入图形`Buffer`后，最终提交`Buffer`到图形队列。
24
25**添加动态链接库**
26CMakeLists.txt中添加以下lib。
27```txt
28libace_ndk.z.so
29libnative_window.so
30```
31
32**头文件**
33```c++
34#include <ace/xcomponent/native_interface_xcomponent.h>
35#include <native_window/external_window.h>
36```
37
381. **获取OHNativeWindow实例**。
39
40    可在[`OH_NativeXComponent_Callback`](../reference/native-apis/_o_h___native_x_component___callback.md)提供的接口中获取OHNativeWindow，下面提供一份代码示例。XComponent模块的具体使用方法请参考[XComponent](../ui/arkts-common-components-xcomponent.md)。
41    1. 在xxx.ets中添加一个XComponent组件。
42        ```ts
43        XComponent({ id: 'xcomponentId', type: 'surface', libraryname: 'entry'})
44            .width(360)
45            .height(360)
46        ```
47    2. 在 native c++ 层获取 NativeXComponent。
48        ```c++
49        napi_value exportInstance = nullptr;
50        // 用来解析出被wrap了NativeXComponent指针的属性
51        napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
52        OH_NativeXComponent *nativeXComponent = nullptr;
53        // 通过napi_unwrap接口，解析出NativeXComponent的实例指针
54        napi_unwrap(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent));
55        ```
56    3. 定义 OH_NativeXComponent_Callback。
57        ```c++
58        // 定义回调函数
59        void OnSurfaceCreatedCB(OH_NativeXComponent* component, void* window)
60        {
61            // 可获取 OHNativeWindow 实例
62            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
63            // ...
64        }
65        void OnSurfaceChangedCB(OH_NativeXComponent* component, void* window)
66        {
67            // 可获取 OHNativeWindow 实例
68            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
69            // ...
70        }
71        void OnSurfaceDestroyedCB(OH_NativeXComponent* component, void* window)
72        {
73            // 可获取 OHNativeWindow 实例
74            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
75            // ...
76        }
77        void DispatchTouchEventCB(OH_NativeXComponent* component, void* window)
78        {
79            // 可获取 OHNativeWindow 实例
80            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
81            // ...
82        }
83        ```
84        ```c++
85        // 初始化 OH_NativeXComponent_Callback
86        OH_NativeXComponent_Callback callback;
87        callback.OnSurfaceCreated = OnSurfaceCreatedCB;
88        callback.OnSurfaceChanged = OnSurfaceChangedCB;
89        callback.OnSurfaceDestroyed = OnSurfaceDestroyedCB;
90        callback.DispatchTouchEvent = DispatchTouchEventCB;
91        ```
92   4. 将 OH_NativeXComponent_Callback 注册给 NativeXComponent。
93        ```c++
94        // 注册回调函数
95        OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback);
96        ```
97
982. **设置OHNativeWindowBuffer的属性**。使用`OH_NativeWindow_NativeWindowHandleOpt`设置`OHNativeWindowBuffer`的属性。
99    ```c++
100    // 设置 OHNativeWindowBuffer 的宽高
101    int32_t code = SET_BUFFER_GEOMETRY;
102    int32_t width = 0x100;
103    int32_t height = 0x100;
104    // 这里的nativeWindow是从上一步骤中的回调函数中获得的
105    int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height);
106    // 设置 OHNativeWindowBuffer 的步长
107    code = SET_STRIDE;
108    int32_t stride = 0x8;
109    ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, stride);
110    ```
111
1123. **从图形队列申请OHNativeWindowBuffer**。
113    ```c++
114    OHNativeWindowBuffer* buffer = nullptr;
115    int fenceFd;
116    // 通过 OH_NativeWindow_NativeWindowRequestBuffer 获取 OHNativeWindowBuffer 实例
117    OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow, &buffer, &fenceFd);
118    // 通过 OH_NativeWindow_GetBufferHandleFromNative 获取 buffer 的 handle
119    BufferHandle* bufferHandle = OH_NativeWindow_GetBufferHandleFromNative(buffer);
120    ```
121
1224. **内存映射mmap**。
123    ```c++
124    #include <sys/mman.h>
125
126    // 使用系统mmap接口拿到bufferHandle的内存虚拟地址
127    void* mappedAddr = mmap(bufferHandle->virAddr, bufferHandle->size, PROT_READ | PROT_WRITE, MAP_SHARED, bufferHandle->fd, 0);
128    if (mappedAddr == MAP_FAILED) {
129        // mmap failed
130    }
131    ```
132
1335. **将生产的内容写入OHNativeWindowBuffer**。
134    ```c++
135    static uint32_t value = 0x00;
136    value++;
137    uint32_t *pixel = static_cast<uint32_t *>(mappedAddr); // 使用mmap获取到的地址来访问内存
138    for (uint32_t x = 0; x < width; x++) {
139        for (uint32_t y = 0;  y < height; y++) {
140            *pixel++ = value;
141        }
142    }
143    ```
144
1455. **提交OHNativeWindowBuffer到图形队列**。
146    ```c++
147    // 设置刷新区域，如果Region中的Rect为nullptr,或者rectNumber为0，则认为OHNativeWindowBuffer全部有内容更改。
148    Region region{nullptr, 0};
149    // 通过OH_NativeWindow_NativeWindowFlushBuffer 提交给消费者使用，例如：显示在屏幕上。
150    OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow, buffer, fenceFd, region);
151    ```
1526. **取消内存映射munmap**。
153    ```c++
154    // 内存使用完记得去掉内存映射
155    int result = munmap(mappedAddr, bufferHandle->size);
156    if (result == -1) {
157        // munmap failed
158    }
159    ```
160