• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# NativeWindow Development
2
3## When to Use
4
5`NativeWindow` is a local platform window of OpenHarmony. It provides APIs for you to create a native window from `Surface`, create a native window buffer from `SurfaceBuffer`, and request and flush a buffer.
6The following scenarios are common for native window development:
7
8* Drawing content using native C++ code and displaying the content on the screen
9* Requesting and flushing a buffer when adapting to EGL `eglswapbuffer`
10
11## Available APIs
12
13| API| Description|
14| -------- | -------- |
15| OH_NativeWindow_CreateNativeWindowFromSurface (void \*pSurface) | Creates a `NativeWindow` instance. A new `NativeWindow` instance is created each time this function is called.|
16| OH_NativeWindow_DestroyNativeWindow (struct NativeWindow \*window) | Decreases the reference count of a `NativeWindow` instance by 1 and, when the reference count reaches 0, destroys the instance.|
17| OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer (void \*pSurfaceBuffer) | Creates a `NativeWindowBuffer` instance. A new `NativeWindowBuffer` instance is created each time this function is called.|
18| OH_NativeWindow_DestroyNativeWindowBuffer (struct NativeWindowBuffer \*buffer) | Decreases the reference count of a `NativeWindowBuffer` instance by 1 and, when the reference count reaches 0, destroys the instance.|
19| OH_NativeWindow_NativeWindowRequestBuffer (struct NativeWindow \*window struct NativeWindowBuffer \*\*buffer, int \*fenceFd) | Requests a `NativeWindowBuffer` through a `NativeWindow` instance for content production.|
20| OH_NativeWindow_NativeWindowFlushBuffer (struct NativeWindow \*window, struct NativeWindowBuffer \*buffer, int fenceFd, Region region) | Flushes the `NativeWindowBuffer` filled with the content to the buffer queue through a `NativeWindow` instance for content consumption.|
21| OH_NativeWindow_NativeWindowCancelBuffer (struct NativeWindow \*window, struct NativeWindowBuffer \*buffer) | Returns the `NativeWindowBuffer` to the buffer queue through a `NativeWindow` instance, without filling in any content. The `NativeWindowBuffer` can be used for another request.|
22| OH_NativeWindow_NativeWindowHandleOpt (struct NativeWindow \*window, int code,...) | Sets or obtains the attributes of a native window, including the width, height, and content format.|
23| OH_NativeWindow_GetBufferHandleFromNative (struct NativeWindowBuffer \*buffer) | Obtains the pointer to a `BufferHandle` of a `NativeWindowBuffer` instance.|
24| OH_NativeWindow_NativeObjectReference (void \*obj) | Adds the reference count of a native object.|
25| OH_NativeWindow_NativeObjectUnreference (void \*obj) | Decreases the reference count of a native object and, when the reference count reaches 0, destroys this object.|
26| OH_NativeWindow_GetNativeObjectMagic (void \*obj) | Obtains the magic ID of a native object.|
27
28
29
30## How to Develop
31
32The following steps describe how to use `OH_NativeXComponent` in OpenHarmony to draw content using native C++ code and display the content on the screen.
33
341. Define an `XComponent` of the `texture` type in `index.ets` for content display.
35   ```js
36    XComponent({ id: 'xcomponentId', type: 'texture', libraryname: 'nativerender'})
37        .borderColor(Color.Red)
38        .borderWidth(5)
39        .onLoad(() => {})
40        .onDestroy(() => {})
41   ```
42
432. Obtain an `OH_NativeXComponent` instance (named `nativeXComponent` in this example) by calling `napi_get_named_property`, and obtain a `NativeWindow` instance by registering the callback of the `OH_NativeXComponent` instance.
44
45    ```c++
46    // Define a NAPI instance.
47    napi_value exportInstance = nullptr;
48    // Define an OH_NativeXComponent instance.
49    OH_NativeXComponent *nativeXComponent = nullptr;
50    // Use the OH_NATIVE_XCOMPONENT_OBJ export instance.
51    napi_getname_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
52    // Convert the NAPI instance to the OH_NativeXComponent instance.
53    napi_unwarp(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent));
54    ```
55
563. Define the callback `OnSurfaceCreated`. During the creation of a `Surface`, the callback is used to initialize the rendering environment, for example, the `Skia` rendering environment, and write the content to be displayed to `NativeWindow`.
57
58    ```c++
59    void OnSufaceCreatedCB(NativeXComponent* component, void* window) {
60        // Obtain the width and height of the native window.
61        uint64_t width_ = 0, height_ = 0;
62        OH_NativeXComponent_GetXComponentSize(nativeXComponent, window, &width_, &height_);
63        // Convert void* into a NativeWindow instance. NativeWindow is defined in native_window/external_window.h.
64        NativeWindow* nativeWindow_ = (NativeWindow*)(window);
65
66        // Set or obtain the NativeWindow attributes by calling OH_NativeWindow_NativeWindowHandleOpt.
67        // 1. Use SET_USAGE to set the usage attribute of the native window, for example, to HBM_USE_CPU_READ.
68        OH_NativeWindow_NativeWindowHandleOpt(nativeWindow_, SET_USAGE, HBM_USE_CPU_READ | HBM_USE_CPU_WRITE |HBM_USE_MEM_DMA);
69        // 2. Use SET_BUFFER_GEOMETRY to set the width and height attributes of the native window.
70        OH_NativeWindow_NativeWindowHandleOpt(nativeWindow_, SET_BUFFER_GEOMETRY, width_, height_);
71        // 3. Use SET_FORMAT to set the format attribute of the native window, for example, to PIXEL_FMT_RGBA_8888.
72        OH_NativeWindow_NativeWindowHandleOpt(nativeWindow_, SET_FORMAT, PIXEL_FMT_RGBA_8888);
73        // 4. Use SET_STRIDE to set the stride attribute of the native window.
74        OH_NativeWindow_NativeWindowHandleOpt(nativeWindow_, SET_STRIDE, 0x8);
75
76        // Obtain the NativeWindowBuffer instance by calling OH_NativeWindow_NativeWindowRequestBuffer.
77        struct NativeWindowBuffer* buffer = nullptr;
78        int fenceFd;
79        OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow_, &buffer, &fenceFd);
80
81        // Obtain the buffer handle by calling OH_NativeWindow_GetNativeBufferHandleFromNative.
82        BufferHandle* bufferHandle = OH_NativeWindow_GetNativeBufferHandleFromNative(buffer);
83
84        // Create a Skia bitmap using BufferHandle.
85        SkBitmap bitmap;
86        SkImageInfo imageInfo = ...
87        bitmap.setInfo(imageInfo, bufferHandle->stride);
88        bitmap.setPixels(bufferHandle->virAddr);
89        // Create Skia Canvas and write the content to the native window.
90        ...
91
92        // After the write operation is complete, flush the buffer by using OH_NativeWindwo_NativeWindowFlushBuffer so that the data is displayed on the screen.
93        Regoin region{nullptr, 0};
94        OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow_, buffer, fenceFd, region)
95    }
96    ```
97
984. Register the callback `OnSurfaceCreated` by using `OH_NativeXComponent_RegisterCallback`.
99
100    ```c++
101    OH_NativeXComponent_Callback &callback_;
102    callback_->OnSurfaceCreated = OnSufaceCreatedCB;
103    callback_->OnSurfaceChanged = OnSufaceChangedCB;
104    callback_->OnSurfaceDestoryed = OnSufaceDestoryedCB;
105    callback_->DispatchTouchEvent = DispatchTouchEventCB;
106    OH_NativeXComponent_RegisterCallback(nativeXComponent, callback_)
107    ```
108