1# Native Window Development 2 3## When to Use 4 5**NativeWindow** is a local platform-based window of OpenHarmony that represents the producer of a graphics queue. 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* Request a graphics buffer by using the NAPI provided by **NativeWindow**, write the produced graphics content to the buffer, and flush the buffer to the graphics queue. 9* Request and flush a buffer when adapting to the **eglswapbuffer** interface at the EGL. 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 (OHNativeWindow \*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 (OHNativeWindowBuffer \*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 (OHNativeWindow \*window, OHNativeWindowBuffer \*\*buffer, int \*fenceFd) | Requests a **NativeWindowBuffer** through a **NativeWindow** instance for content production.| 20| OH_NativeWindow_NativeWindowFlushBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*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_NativeWindowAbortBuffer (OHNativeWindow \*window, OHNativeWindowBuffer \*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 (OHNativeWindow \*window, int code,...) | Sets or obtains the attributes of a native window, including the width, height, and content format.| 23| OH_NativeWindow_GetBufferHandleFromNative (OHNativeWindowBuffer \*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| OH_NativeWindow_NativeWindowSetScalingMode (OHNativeWindow \*window, uint32_t sequence, OHScalingMode scalingMode) | Sets the scaling mode of the native window.| 28| OH_NativeWindow_NativeWindowSetMetaData(OHNativeWindow \*window, uint32_t sequence, int32_t size, const OHHDRMetaData \*metaData) | Sets the HDR static metadata of the native window.| 29| OH_NativeWindow_NativeWindowSetMetaDataSet(OHNativeWindow \*window, uint32_t sequence, OHHDRMetadataKey key, int32_t size, const uint8_t \*metaData) | Sets the HDR static metadata set of the native window.| 30| OH_NativeWindow_NativeWindowSetTunnelHandle(OHNativeWindow \*window, const OHExtDataHandle \*handle) | Sets the tunnel handle to the native window.| 31 32## How to Develop 33 34The following describes how to use the NAPI provided by **NativeWindow** to request a graphics buffer, write the produced graphics content to the buffer, and flush the buffer to the graphics queue. 35 361. Obtain a **NativeWindow** instance, which can be obtained by running the APIs provided by **OH_NativeXComponent_Callback**. 37 1. Define **XComponent** in an .ets file. 38 ```ts 39 XComponent({ id: 'xcomponentId', type: 'surface', libraryname: 'nativerender'}) 40 .onLoad((context) => { 41 this.context = context; 42 }) 43 .onDestroy(() => { 44 }) 45 ``` 46 2. Obtain **NativeXComponent** at the native C++ layer. 47 ```c++ 48 napi_value exportInstance = nullptr; 49 napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance); 50 51 OH_NativeXComponent *nativeXComponent = nullptr; 52 napi_unwrap(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent)); 53 54 char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = { }; 55 uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1; 56 OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize); 57 ``` 58 3. Define **OH_NativeXComponent_Callback**. 59 ```c++ 60 // Define the callback. 61 void OnSurfaceCreatedCB(OH_NativeXComponent* component, void* window) 62 { 63 // Obtain a NativeWindow instance. 64 OHNativeWindow* nativeWindow = window; 65 // ... 66 } 67 void OnSurfaceChangedCB(OH_NativeXComponent* component, void* window) 68 { 69 // Obtain a NativeWindow instance. 70 OHNativeWindow* nativeWindow = window; 71 // ... 72 } 73 void OnSurfaceDestroyedCB(OH_NativeXComponent* component, void* window) 74 { 75 // Obtain a NativeWindow instance. 76 OHNativeWindow* nativeWindow = window; 77 // ... 78 } 79 void DispatchTouchEventCB(OH_NativeXComponent* component, void* window) 80 { 81 // Obtain a NativeWindow instance. 82 OHNativeWindow* nativeWindow = window; 83 // ... 84 } 85 ``` 86 ```c++ 87 // Initialize OH_NativeXComponent_Callback. 88 OH_NativeXComponent_Callback callback_; 89 callback_->OnSurfaceCreated = OnSurfaceCreatedCB; 90 callback_->OnSurfaceChanged = OnSurfaceChangedCB; 91 callback_->OnSurfaceDestroyed = OnSurfaceDestroyedCB; 92 callback_->DispatchTouchEvent = DispatchTouchEventCB; 93 ``` 94 4. Register **OH_NativeXComponent_Callback** with **NativeXComponent**. 95 ```c++ 96 OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback_); 97 ``` 98 992. Set the attributes of a native window buffer by using **OH_NativeWindow_NativeWindowHandleOpt**. 100 ```c++ 101 // Set the read and write scenarios of the native window buffer. 102 int code = SET_USAGE; 103 int32_t usage = BUFFER_USAGE_CPU_READ | BUFFER_USAGE_CPU_WRITE | BUFFER_USAGE_MEM_DMA; 104 int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, usage); 105 // Set the width and height of the native window buffer. 106 code = SET_BUFFER_GEOMETRY; 107 int32_t width = 0x100; 108 int32_t height = 0x100; 109 ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height); 110 // Set the step of the native window buffer. 111 code = SET_STRIDE; 112 int32_t stride = 0x8; 113 ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, stride); 114 // Set the format of the native window buffer. 115 code = SET_FORMAT; 116 int32_t format = PIXEL_FMT_RGBA_8888; 117 ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, format); 118 ``` 119 1203. Request a native window buffer from the graphics queue. 121 ```c++ 122 struct NativeWindowBuffer* buffer = nullptr; 123 int fenceFd; 124 // Obtain the NativeWindowBuffer instance by calling OH_NativeWindow_NativeWindowRequestBuffer. 125 OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow_, &buffer, &fenceFd); 126 // Obtain the buffer handle by calling OH_NativeWindow_GetNativeBufferHandleFromNative. 127 BufferHandle* bufferHandle = OH_NativeWindow_GetNativeBufferHandleFromNative(buffer); 128 ``` 129 1304. Write the produced content to the native window buffer. 131 ```c++ 132 auto image = static_cast<uint8_t *>(buffer->sfbuffer->GetVirAddr()); 133 static uint32_t value = 0x00; 134 value++; 135 136 uint32_t *pixel = static_cast<uint32_t *>(image); 137 for (uint32_t x = 0; x < width; x++) { 138 for (uint32_t y = 0; y < height; y++) { 139 *pixel++ = value; 140 } 141 } 142 ``` 143 1445. Flush the native window buffer to the graphics queue. 145 ```c++ 146 // Set the refresh region. If Rect in Region is a null pointer or rectNumber is 0, all contents in the native window buffer are changed. 147 Region region{nullptr, 0}; 148 // Flush the buffer to the consumer through OH_NativeWindow_NativeWindowFlushBuffer, for example, by displaying it on the screen. 149 OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow_, buffer, fenceFd, region); 150 ``` 151