• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Native Window Development
2
3## When to Use
4
5The native window module is a local platform-based window that represents the producer of a graphics queue. It provides APIs for you to request and flush a buffer and configure buffer attributes.
6
7The following scenarios are common for native window development:
8
9* Request a graphics buffer by using the native window API, write the produced graphics content to the buffer, and flush the buffer to the graphics queue.
10* Request and flush a buffer when adapting to the **eglswapbuffer** interface at the EGL.
11
12## Available APIs
13
14| API| Description|
15| -------- | -------- |
16| OH_NativeWindow_NativeWindowRequestBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*\*buffer, int \*fenceFd) | Requests an **OHNativeWindowBuffer** through an **OHNativeWindow** instance for content production.|
17| OH_NativeWindow_NativeWindowFlushBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*buffer, int fenceFd, Region region) | Flushes the **OHNativeWindowBuffer** filled with the produced content to the buffer queue through an **OHNativeWindow** instance for content consumption.|
18| OH_NativeWindow_NativeWindowHandleOpt (OHNativeWindow \*window, int code,...) | Sets or obtains the attributes of an **OHNativeWindow** instance, including the width, height, and content format.|
19
20For details about the APIs, see [native_window](../reference/native-apis/_native_window.md).
21
22## How to Develop
23
24The following describes how to use the native window APIs to request a graphics buffer, write the produced graphics content to the buffer, and flush the buffer to the graphics queue.
25
26**Adding Dynamic Link Libraries**
27
28Add the following libraries to **CMakeLists.txt**:
29```txt
30libace_ndk.z.so
31libnative_window.so
32```
33
34**Including Header Files**
35```c++
36#include <ace/xcomponent/native_interface_xcomponent.h>
37#include <native_window/external_window.h>
38```
39
401. Obtain an **OHNativeWindow** instance.
41
42    You can call the APIs provided by [OH_NativeXComponent_Callback](../reference/native-apis/_o_h___native_x_component___callback.md) to obtain an **OHNativeWindow** instance. An example code snippet is provided below. For details about how to use the **\<XComponent>**, see [XComponent Development](xcomponent-guidelines.md).
43    1. Add an **\<XComponent>** to the .ets file.
44        ```ts
45        XComponent({ id: 'xcomponentId', type: 'surface', libraryname: 'entry'})
46            .width(360)
47            .height(360)
48        ```
49    2. Obtain **NativeXComponent** at the native C++ layer.
50        ```c++
51        napi_value exportInstance = nullptr;
52        // Parse the attribute of the wrapped NativeXComponent pointer.
53        napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
54        OH_NativeXComponent *nativeXComponent = nullptr;
55        // Use the napi_unwrap API to parse the NativeXComponent instance pointer.
56        napi_unwrap(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent));
57        // Obtain the XComponent ID.
58        char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {};
59        uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
60        OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize);
61        ```
62    3. Define **OH_NativeXComponent_Callback**.
63        ```c++
64        // Define the callback.
65        void OnSurfaceCreatedCB(OH_NativeXComponent* component, void* window)
66        {
67            // Obtain an OHNativeWindow instance.
68            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
69            // ...
70        }
71        void OnSurfaceChangedCB(OH_NativeXComponent* component, void* window)
72        {
73            // Obtain an OHNativeWindow instance.
74            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
75            // ...
76        }
77        void OnSurfaceDestroyedCB(OH_NativeXComponent* component, void* window)
78        {
79            // Obtain an OHNativeWindow instance.
80            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
81            // ...
82        }
83        void DispatchTouchEventCB(OH_NativeXComponent* component, void* window)
84        {
85            // Obtain an OHNativeWindow instance.
86            OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
87            // ...
88        }
89        ```
90        ```c++
91        // Initialize OH_NativeXComponent_Callback.
92        OH_NativeXComponent_Callback callback;
93        callback.OnSurfaceCreated = OnSurfaceCreatedCB;
94        callback.OnSurfaceChanged = OnSurfaceChangedCB;
95        callback.OnSurfaceDestroyed = OnSurfaceDestroyedCB;
96        callback.DispatchTouchEvent = DispatchTouchEventCB;
97        ```
98   4. Register **OH_NativeXComponent_Callback** with **NativeXComponent**.
99        ```c++
100        // Register the callback.
101        OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback);
102        ```
103
1042. Set the attributes of an **OHNativeWindowBuffer** by using **OH_NativeWindow_NativeWindowHandleOpt**.
105    ```c++
106    // Set the width and height of the OHNativeWindowBuffer.
107    int32_t code = SET_BUFFER_GEOMETRY;
108    int32_t width = 0x100;
109    int32_t height = 0x100;
110    // The nativeWindow instance is obtained from the callback in the previous step.
111    int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height);
112    ```
113
1143. Request an **OHNativeWindowBuffer** from the graphics queue.
115    ```c++
116    OHNativeWindowBuffer* buffer = nullptr;
117    int fenceFd;
118    // Obtain the OHNativeWindowBuffer instance by calling OH_NativeWindow_NativeWindowRequestBuffer.
119    OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow, &buffer, &fenceFd);
120    // Obtain the buffer handle by calling OH_NativeWindow_GetBufferHandleFromNative.
121    BufferHandle* bufferHandle = OH_NativeWindow_GetBufferHandleFromNative(buffer);
122    ```
123
1244. Map memory.
125    ```c++
126    #include <sys/mman.h>
127
128    // Use mmap() to map the shared memory allocated to the buffer handle to the user space. Image data can be written to the buffer handle by using the obtained virtual address.
129    // bufferHandle->virAddr indicates the start address of the buffer handle in the shared memory, and bufferHandle->size indicates the memory usage of the buffer handle in the shared memory.
130    void* mappedAddr = mmap(bufferHandle->virAddr, bufferHandle->size, PROT_READ | PROT_WRITE, MAP_SHARED, bufferHandle->fd, 0);
131    if (mappedAddr == MAP_FAILED) {
132        // mmap failed
133    }
134    ```
135
1365. Write the produced content to the **OHNativeWindowBuffer**.
137    ```c++
138    static uint32_t value = 0x00;
139    value++;
140    uint32_t *pixel = static_cast<uint32_t *>(mappedAddr); // Use the address obtained by mmap() to access the memory.
141    for (uint32_t x = 0; x < width; x++) {
142        for (uint32_t y = 0;  y < height; y++) {
143            *pixel++ = value;
144        }
145    }
146    ```
147
1485. Flush the **OHNativeWindowBuffer** to the graphics queue.
149    ```c++
150    // Set the refresh region. If Rect in Region is a null pointer or rectNumber is 0, all contents in the OHNativeWindowBuffer are changed.
151    Region region{nullptr, 0};
152    // Flush the buffer to the consumer through OH_NativeWindow_NativeWindowFlushBuffer, for example, by displaying it on the screen.
153    OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow, buffer, fenceFd, region);
154    ```
1556. Unmap memory.
156    ```c++
157    // Unmap the memory when the memory is no longer required.
158    int result = munmap(mappedAddr, bufferHandle->size);
159    if (result == -1) {
160        // munmap failed
161    }
162    ```
163