NativeWindow 开发指导

场景介绍

NativeWindow是OpenHarmony本地平台化窗口，表示图形队列的生产者端。接口能力包括从Surface构建NativeWindow的能力，从SurfaceBuffer构建出NativeWindowBuffer的能力，开发者可以通过NativeWindow接口进行申请和提交Buffer。 针对NativeWindow，常见的开发场景如下：

• 通过NativeWindow提供的NAPI接口申请图形Buffer，并将生产图形内容写入图形Buffer，最终提交Buffer到图形队列
• 在适配EGL层的eglswapbuffer接口时，进行申请和提交Buffer

接口说明

详细的接口说明请参考native_window。

开发步骤

以下步骤描述了在OpenHarmony中如何使用NativeWindow提供的NAPI接口，申请图形Buffer，并将生产图形内容写入图形Buffer后，最终提交Buffer到图形队列。

1. 获取NativeWindow实例。可在OH_NativeXComponent_Callback提供的接口中获取。

   1. 在xxx.ets 中定义 XComponent。

      XComponent({ id: 'xcomponentId', type: 'surface', libraryname: 'nativerender'})
          .onLoad((context) => {
              this.context = context;
          })
          .onDestroy(() => {
          })
      

   2. 在 native c++ 层获取 NativeXComponent。

      napi_value exportInstance = nullptr;
      napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
      
      OH_NativeXComponent *nativeXComponent = nullptr;
      napi_unwrap(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent));
      
      char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = { };
      uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
      OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize);
      

   3. 定义 OH_NativeXComponent_Callback。

      // 定义回调函数
      void OnSurfaceCreatedCB(OH_NativeXComponent* component, void* window)
      {
          // 可获取 NativeWindow 实例
          OHNativeWindow* nativeWindow = window;
          // ...
      }
      void OnSurfaceChangedCB(OH_NativeXComponent* component, void* window)
      {
          // 可获取 NativeWindow 实例
          OHNativeWindow* nativeWindow = window;
          // ...
      }
      void OnSurfaceDestroyedCB(OH_NativeXComponent* component, void* window)
      {
          // 可获取 NativeWindow 实例
          OHNativeWindow* nativeWindow = window;
          // ...
      }
      void DispatchTouchEventCB(OH_NativeXComponent* component, void* window)
      {
          // 可获取 NativeWindow 实例
          OHNativeWindow* nativeWindow = window;
          // ...
      }
      

      // 初始化 OH_NativeXComponent_Callback
      OH_NativeXComponent_Callback callback_;
      callback_->OnSurfaceCreated = OnSurfaceCreatedCB;
      callback_->OnSurfaceChanged = OnSurfaceChangedCB;
      callback_->OnSurfaceDestroyed = OnSurfaceDestroyedCB;
      callback_->DispatchTouchEvent = DispatchTouchEventCB;
      

   4. 将 OH_NativeXComponent_Callback 注册给 NativeXComponent。

      OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback_);
      

2. 设置NativeWindowBuffer的属性。使用OH_NativeWindow_NativeWindowHandleOpt设置NativeWindowBuffer的属性。

   // 设置 NativeWindowBuffer 的读写场景
   int code = SET_USAGE;
   int32_t usage = BUFFER_USAGE_CPU_READ | BUFFER_USAGE_CPU_WRITE | BUFFER_USAGE_MEM_DMA;
   int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, usage);
   // 设置 NativeWindowBuffer 的宽高
   code = SET_BUFFER_GEOMETRY;
   int32_t width = 0x100;
   int32_t height = 0x100;
   ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height);
   // 设置 NativeWindowBuffer 的步长
   code = SET_STRIDE;
   int32_t stride = 0x8;
   ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, stride);
   // 设置 NativeWindowBuffer 的格式
   code = SET_FORMAT;
   int32_t format = PIXEL_FMT_RGBA_8888;
   ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, format);
   

3. 从图形队列申请NativeWindowBuffer。

   struct NativeWindowBuffer* buffer = nullptr;
   int fenceFd;
   // 通过 OH_NativeWindow_NativeWindowRequestBuffer 获取 NativeWindowBuffer 实例
   OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow_, &buffer, &fenceFd);
   // 通过 OH_NativeWindow_GetNativeBufferHandleFromNative 获取 buffer 的 handle
   BufferHandle* bufferHandle = OH_NativeWindow_GetNativeBufferHandleFromNative(buffer);
   

4. 将生产的内容写入NativeWindowBuffer。

   auto image = static_cast<uint8_t *>(buffer->sfbuffer->GetVirAddr());
   static uint32_t value = 0x00;
   value++;
   
   uint32_t *pixel = static_cast<uint32_t *>(image);
   for (uint32_t x = 0; x < width; x++) {
       for (uint32_t y = 0;  y < height; y++) {
           *pixel++ = value;
       }
   }
   

5. 提交NativeWindowBuffer到图形队列。

   // 设置刷新区域，如果Region中的Rect为nullptr,或者rectNumber为0，则认为NativeWindowBuffer全部有内容更改。
   Region region{nullptr, 0};
   // 通过OH_NativeWindow_NativeWindowFlushBuffer 提交给消费者使用，例如：显示在屏幕上。
   OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow_, buffer, fenceFd, region);
   

相关实例

针对NativeWindow的使用，有以下相关实例可供参考：

• 使用NativeWindow接口获取并提交Buffer