• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# XComponent组件对接Vulkan
2### 介绍
3XComponent组件作为绘制组件, 可用于满足开发者较为复杂的自定义绘制需求, 如相机预览流显示和游戏画面绘制。
4该组件分为`surface`类型和`component`类型, 可通过指定`type`字段来确定。 其中`surface`类型可支持开发者将相关数据传入XComponent单独拥有的surface来渲染画面。
5本篇示例基于"Native C++"模板, 演示了XComponent调用Vulkan API完成三角形绘制, 并将渲染结果显示在屏幕上的流程。
6
7示例主要使用[@ohos.app.ability.UIAbility](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/ui/Readme-CN.md),
8[@ohos.hilog](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/dfx),
9[@ohos.window](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/windowmanager/window-overview.md),
10[NativeWindow](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/graphics/native-window-guidelines.md),
11[Vulkan](https://gitee.com/openharmony/docs/tree/master/zh-cn/application-dev/reference/native-lib)接口。
12
13### 效果预览
14如下图所示, 打开应用, 屏幕中心会绘制一个旋转中的三角形, 可以点击'stop/start'按钮控制三角形的旋转状态。
15![image](screenshots/device/sample.png)
16### 工程目录
17
18```
19entry/src/main/
20|---cpp
21|   |---common
22|   |   |---logger_common.h                          // Hilog日志宏定义
23|   |---render
24|   |   |---vulkan
25|   |   |   |---shader
26|   |   |   |   |   |---triangle.frag                // fragment shader
27|   |   |   |   |   |---triangle.vert                // vertex shader
28|   |   |   |---vulkan_example.h                     // 本示例中用于实现三角形绘制的VulkanExample类
29|   |   |   |---vulkan_example.cpp
30|   |   |   |---vulkan_utils.h                       // 本示例中用于加载Vulkan动态库以及Vulkan函数
31|   |   |   |---vulkan_utils.cpp
32|   |   |---plugin_manager.h                         // 对接XComponent
33|   |   |---plugin_manager.cpp
34|   |   |---plugin_render.h                          // 对接后端VulkanExample, 使能Vulkan能力
35|   |   |---plugin_render.cpp
36|   |---CMakeLists.txt
37|   |---plugin.cpp                                   // 注册NAPI
38|---ets
39|   |---entryability
40|   |   |---EntryAbility.ts                          // 定义组件的入口点以及日志类封装
41|   |---pages
42|   |   |---Index.ets                                // 应用界面布局描述以及shader二进制加载
43```
44
45### 具体实现
46#### XComponent
47XComponent组件可通过NDK接口为开发者在C++层提供NativeWindow用于创建Vulkan环境.
48##### NAPI注册
49首先填充`napi_module`结构体, 然后调用`napi_module_register`函数注册.
50```
51// entry/src/main/cpp/plugin.cpp
52static napi_module SampleModule = {
53    .nm_version = 1,
54    .nm_flags = 0,
55    .nm_filename = nullptr,
56    .nm_register_func = Init, // 指定加载C++层编译的动态so的NAPI注册函数名
57    .nm_modname = "nativerender", // 指定被NAPI加载的so的名称, 应与cpp目录下CMakeLists.txt指定的编译so名称一致
58    .nm_priv = ((void *)0),
59    .reserved = {0},
60};
61
62extern "C" __attribute__((constructor)) void RegisterEntryModule(void) {
63    napi_module_register(&SampleModule);
64}
65```
66注意`napi_module`中的成员变量`.nm_register_func`指定了加载so时的注册函数名为`Init`, 我们通过修改该函数来控制注册NAPI时要执行的操作.
67在Init函数中我们封装了一个单例类PluginManager, 以应对多个NativeXComponent实例的情况.
68```
69// entry/src/main/cpp/plugin.cpp
70static napi_value Init(napi_env env, napi_value exports)
71{
72    if (!PluginManager::GetInstance()->Init(env, exports)) {
73        LOGE("Failed to init NAPI!");
74    }
75    return exports;
76}
77```
78##### PluginManager
79PluginManager::Init函数中主要做了两件事
80###### 获取NativeXComponent指针
81`NativeXComponent`为`XComponent`提供了在`native`层的实例, 可作为ts/js层与`native`层`XComponent`绑定的桥梁.
82```
83// entry/src/main/cpp/render/plugin_manager.cpp
84bool PluginManager::Init(napi_env env, napi_value exports)
85{
86    napi_value exportInstance = nullptr;
87    OH_NativeXComponent *nativeXComponent = nullptr; // NativeXComponent指针
88    // 首先调用napi_get_name_property, 传入OH_NATIVE_XCOMPONENT_OBJ, 解析得到exportInstance.
89    napi_status status = napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
90    // 然后调用napi_unwrap, 从exportInstance中解析得到nativeXComponent实例指针
91    status = napi_unwrap(env, exportInstance, reinterpret_cast<void **>(&nativeXComponent));
92    ...
93}
94```
95
96###### 创建和初始化PluginRender
97`PluginManager`可以管理多个`PluginRender`实例（示例中只使用一个）, 在`PluginManager::Init`中进行`PluginRender`的创建和初始化.
98实际对接`Vulkan`渲染后端是通过`PluginRender`类完成的, 每个`XComponent`实例对应一个`PluginRender`实例, 通过`XComponentId`进行区分.
99```
100// entry/src/main/cpp/render/plugin_manager.cpp
101bool PluginManager::Init(napi_env env, napi_value exports)
102{
103    // 省略获取nativeXComponent的部分
104
105    // 获取XComponentId
106    char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {};
107    uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
108    // get nativeXComponent Id
109    int32_t ret = OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize);
110    if (ret != OH_NATIVEXCOMPONENT_RESULT_SUCCESS) {
111        LOGE("PluginManager::Export OH_NativeXComponent_GetXComponentId failed, ret:%{public}d", ret);
112        return false;
113    }
114
115    std::string id(idStr);
116    // 获取PluginManger单例指针
117    auto context = PluginManager::GetInstance();
118    if (context != nullptr) {
119        context->SetNativeXComponent(id, nativeXComponent);
120        // 传入XComponentId初始化PluginRender
121        auto render = context->GetRender(id);
122        if (render == nullptr) {
123            LOGE("Failed to get render context!");
124            return false;
125        }
126        render->Export(env, exports); // 注册开放给js/ts层调用的native函数
127        render->SetNativeXComponent(nativeXComponent); // 设置navetiveXComponent指针和回调函数
128        return true;
129    }
130    LOGE("Failed to get PluginManager instance! XComponentId:%{public}s", idStr);
131    return false;
132```
133
134##### PluginRender
135###### 注册XComponent事件回调
136在`PluginManager::Init`中解析得到`NativeXComponent`指针后, 通过`PluginRender::SetNativeXComponent`将指针传递给`PluginRender`并调用`OH_NativeXComponent_RegisterCallback`注册事件回调.
137```
138// entry/src/main/cpp/render/plugin_render.cpp
139OH_NativeXComponent_Callback PluginRender::callback_;
140
141OH_NativeXComponent_Callback *PluginRender::GetNXComponentCallback() {
142    return &PluginRender::callback_;
143}
144
145PluginRender::PluginRender(std::string &id) : id_(id), component_(nullptr)
146{
147    auto renderCallback = PluginRender::GetNXComponentCallback();
148    renderCallback->OnSurfaceCreated = OnSurfaceCreatedCB;     // surface创建成功后触发,开发者可以从中获取native window的句柄
149    renderCallback->OnSurfaceChanged = OnSurfaceChangedCB;     // surface发生变化后触发,开发者可以从中获取native window的句柄以及XComponent的变更信息
150    renderCallback->OnSurfaceDestroyed = OnSurfaceDestroyedCB; // surface销毁时触发,开发者可以在此释放资源
151    renderCallback->DispatchTouchEvent = DispatchTouchEventCB; // XComponent的touch事件回调接口,开发者可以从中获得此次touch事件的信息
152}
153
154void PluginRender::SetNativeXComponent(OH_NativeXComponent *component)
155{
156    component_ = component;
157    OH_NativeXComponent_RegisterCallback(component_, &PluginRender::callback_); // 注册事件回调
158}
159```
160###### 定义暴露给前端的方法
161`XComponent`支持将`native`方法暴露给前端调用, 一般将该函数命名为`Export`, 它会通过js引擎绑定到js层的一个js对象
162开发者首先需要填充结构体`napi_property_descriptor`, 再调用`napi_define_properties`完成注册.
163下面的示例代码中将native方法`stopOrStart`暴露给前端, 后续会关键到触控事件, 使得用户能通过按钮控制本示例中三角形的旋转.
164```
165// entry/src/main/cpp/render/plugin_render.cpp
166napi_value PluginRender::Export(napi_env env, napi_value exports)
167{
168    napi_property_descriptor desc[] = {
169        { "stopOrStart", nullptr, PluginRender::NapiStopMovingOrRestart, nullptr, nullptr, nullptr,
170            napi_default, nullptr}
171    };
172    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
173    return exports;
174}
175```
176###### 调用Vulkan后端
177在`Surface`创建时触发的回调函数里创建`Vulkan`环境和渲染管线, 并将绘制函数绑定到主线程.
178```
179// entry/src/main/cpp/render/plugin_render.cpp
180void PluginRender::OnSurfaceCreated(OH_NativeXComponent *component, void *window)
181{
182    int32_t ret = OH_NativeXComponent_GetXComponentSize(component, window, &width_, &height_);
183    if (vulkanExample_ == nullptr) {
184        vulkanExample_ = std::make_unique<vkExample::VulkanExample>();
185        vulkanExample_->SetupWindow(static_cast<OHNativeWindow *>(window));
186        if (!vulkanExample_->InitVulkan()) {
187            LOGE("PluginRender::OnSurfaceCreated vulkanExample initVulkan failed!");
188            return;
189        }
190        vulkanExample_->SetUp();
191        renderThread_ = std::thread(std::bind(&PluginRender::RenderThread, this));
192    }
193}
194
195void PluginRender::RenderThread()
196{
197    while (vulkanExample_ != nullptr && vulkanExample_->IsInited()) {
198        std::unique_lock<std::mutex> locker(mutex_);
199        if (isTriangleRotational_) {
200            vulkanExample_->RenderLoop();
201        } else {
202            con_.wait(locker);
203        }
204    }
205}
206```
207
208#### Vulkan后端
209本示例中用于绘制三角形的`Vulkan`后端被封装成了类`VulkanExample`, 它对外部暴露6个接口:
210```
211bool InitVulkan();                             // 用于初始化Vulkan环境, 包括加载vulkan动态库, 创建Instance, 选择PhysicalDevice以及创建LogicalDevice
212void SetupWindow(NativeWindow* nativeWindow);  // 将NativeXComponent的NativeWindow指针传入, 用于surface创建
213void SetUp();                                  // 创建Swapchain, ImageView及渲染相关组件
214void RenderLoop();                             // 在渲染线程循环调用, 用于绘制三角形
215bool IsInited() const;                         // 判断Vulkan环境是否初始化成功
216void SetRecreateSwapChain();                   // 设置下次渲染前重建swapchain
217```
218因为本示例主要用于展示`XComponent`组件调用`Vulkan`API的流程, 因此对Vulkan绘制三角形的一般流程不做讲解（相关知识可参考[Vulkan官方指导](https://vulkan-tutorial.com/)).
219仅讲解与`XComponent`以及`OpenHarmony`相关的部分, 更多`OpenHarmony VulkanAPI`使用指导可参考[鸿蒙Vulkan](https://gitee.com/openharmony/docs/tree/master/zh-cn/application-dev/reference/native-lib).
220##### libvulkan.so动态库加载
221OpenHarmony操作系统中Vulkan动态库的名称是`libvulkan.so`, 可通过`dlopen`函数加载.
222
223示例代码：
224```
225#include <dlfcn.h>
226
227const char* path_ = "libvulkan.so";
228void libVulkan = dlopen(path_, RTLD_NOW | RTLD_LOCAL);
229```
230
231##### Vulkan函数加载
232Vulkan函数分为`Instance`域函数, `PhysicalDevice`域函数, `Device`域函数.
233
234`Instance`域函数中的`全局函数`可通过`dlsym`函数获取其函数指针.
235
236示例代码：
237```
238// 全局函数加载
239#include <dlfcn.h>
240// 省略libvulkan.so的加载
241PFN_vkEnumerateInstanceExtensionProperties vkEnumerateInstanceExtensionProperties =
242    reinterpret_cast<PFN_vkEnumerateInstanceExtensionProperties>(dlsym(libVulkan, "vkEnumerateInstanceExtensionProperties"));
243PFN_vkEnumerateInstanceLayerProperties vkEnumerateInstanceLayerProperties =
244    reinterpret_cast<PFN_vkEnumerateInstanceLayerProperties>(dlsym(libVulkan, "vkEnumerateInstanceLayerProperties"));
245PFN_vkCreateInstance vkCreateInstance =
246    reinterpret_cast<PFN_vkCreateInstance>(dlsym(libVulkan, "vkCreateInstance"));
247PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr =
248    reinterpret_cast<PFN_vkGetInstanceProcAddr>(dlsym(libVulkan, "vkGetInstanceProcAddr"));
249PFN_vkGetDeviceProcAddr vkGetDeviceProcAddr =
250    reinterpret_cast<PFN_vkGetDeviceProcAddr>(dlsym(libVulkan, "vkGetDeviceProcAddr"));
251```
252
253在获取`vkGetInstanceProcAddr`函数后, 可通过它加载`Instance`域函数和`PhysicalDevice`域函数; 在获取`vkGetDeviceProcAddr`函数后, 可通过它加载`Device`域函数.
254
255示例代码：
256```
257// Instance域函数加载
258PFN_vkCreateDevice vkCreateDevice =
259    reinterpret_cast<PFN_vkCreateDevice>(vkGetInstanceProcAddr(instance, "vkCreateDevice"));
260
261// Device域函数加载
262PFN_vkCreateSwapchainKHR vkCreateSwapchainKHR =
263    reinterpret_cast<PFN_vkCreateSwapchainKHR>(vkGetDeviceProcAddr(device, "vkCreateSwapchainKHR"));
264```
265##### Instance创建
266创建`Instance`时, 为保证后续能成功创建`OpenHarmony`平台下的`surface`, 需要开启extension `VK_OHOS_SURFACE_EXTENSION_NAME`和`VK_KHR_SURFACE_EXTENSION_NAME`.
267
268示例代码：
269```
270bool VulkanExample::CreateInstance() {
271    VkInstanceCreateInfo createInfo{};
272    createInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
273    ...
274    // 省略其他成员变量定义过程
275    ...
276    std::vector<const char *> extensions = { VK_KHR_SURFACE_EXTENSION_NAME, VK_OHOS_SURFACE_EXTENSION_NAME };
277    createInfo.enabledExtensionCount = static_cast<uint32_t>(extensions.size());
278    createInfo.ppEnabledExtensionNames = extensions.data();
279    if (vkCreateInstance(&createInfo, nullptr, &instance) != VK_SUCCESS) {
280        LOGE("Failed to create instance!");
281        return false;
282    }
283    return true;
284}
285```
286##### Surface创建
287OHOS上的`surface`创建需要填写结构体`VkSurfaceCreateInfoOHOS`, XCompoenent通过`SetupWindow`函数传入`window`指针用于`surface`的创建.
288
289示例代码：
290```
291// window为VulkanExample的成员变量, 其类型为NativeWindow*
292void VulkanExample::SetupWindow(NativeWindow* nativeWindow)
293{
294    window = nativeWindow;
295}
296
297bool VulkanExample::CreateSurface() {
298    VkSurfaceCreateInfoOHOS surfaceCreateInfo{};
299    surfaceCreateInfo.sType = VK_STRUCTURE_TYPE_SURFACE_CREATE_INFO_OHOS;
300    if (window == nullptr) {
301        LOGE("Nativewindow is nullptr. Failed to create surface!");
302        return false;
303    }
304    surfaceCreateInfo.window = window;
305    if (vkCreateSurfaceOHOS(instance, &surfaceCreateInfo, nullptr, &surface) != VK_SUCCESS) {
306        LOGE("Failed to create OHOS surface!");
307        return false;
308    }
309    return true;
310}
311
312```
313### 相关权限
314本示例不涉及特殊系统权限。
315### 依赖
316本示例不依赖其他sample。
317### 约束与限制
3181. 本示例要求设备底层驱动已实现[Vulkan API接口](https://gitee.com/openharmony/docs/tree/master/zh-cn/application-dev/reference/native-lib), rk开发板目前不支持(需厂商驱动实现)。
3192. 本示例基于OpenHarmony API 11 SDK(4.1.7.5)。
320   如果想要在HarmonyOS工程上运行, 需保证HarmonyOS SDK版本为API10及以上, 运行方法如下：
321
322   1. 新建一个HarmonyOS Native C++工程;
323   2. 将本工程AppScope/resources/rawfile目录拷贝至新工程AppScope/resources目录下;
324   3. 删除新工程entry/src目录, 将本工程entry目录下所有文件拷贝至新工程的entry目录下。
3253. 本示例需要使用DevEco Studio版本号(4.0 Release)及以上版本才可编译运行。
326### 下载
327如需单独下载本工程,执行如下命令：
328```
329git init
330git config core.sparsecheckout true
331echo code/BasicFeature/Native/NdkVulkan/ > .git/info/sparse-checkout
332git remote add origin https://gitee.com/openharmony/applications_app_samples.git
333git pull origin master
334```