• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Vulkan Development
2
3## When to Use
4
5Vulkan is a set of graphics APIs for 2D and 3D rendering. To start with, you need to create a **VkSurfaceKHR** instance, which works with the **OHNativeWindow** module to implement buffer recycling.
6
7A **VkSurfaceKHR** instance is obtained through an **OHNativeWindow**, which is obtained from the **XComponent**. Therefore, the **OHNativeWindow** module must be used together with the **XComponent** and **NativeWindow** modules.
8
9## Available APIs
10
11| API                                                      | Description                  |
12| ------------------------------------------------------------ | ---------------------- |
13| vkCreateSurfaceOHOS (VkInstance instance, const VkSurfaceCreateInfoOHOS\* pCreateInfo, const VkAllocationCallbacks\* pAllocator, VkSurfaceKHR\* pSurface) | Creates a **VkSurfaceKHR** instance.|
14
15For details about the APIs, see [Vulkan](vulkan.md).
16
17## How to Develop
18
19The following steps illustrate how to create a **VkSurfaceKHR** instance.
20
21To use the extended APIs, define the macro **VK_USE_PLATFORM_OHOS** in the **CMakeLists.txt** file.
22
23```txt
24ADD_DEFINITIONS(-DVK_USE_PLATFORM_OHOS=1)
25```
26
27**Adding Dynamic Link Libraries**
28
29Add the following libraries to **CMakeLists.txt**:
30
31```txt
32libace_ndk.z.so
33libnative_window.so
34libvulkan.so
35```
36
37> **NOTE**
38>
39> When the **dlopen** function is used to link the **libvulkan.so** dynamic library in a program, you do not need to add dependencies in CMake. Otherwise, symbol conflicts occur.
40
41**Including Header Files**
42
43```c++
44#include <ace/xcomponent/native_interface_xcomponent.h>
45#include <native_window/external_window.h>
46#include <vulkan/vulkan.h>
47```
48
491. Create a Vulkan instance.
50
51   ```c++
52   VkInstance instance = VK_NULL_HANDLE;
53
54   VkApplicationInfo appInfo = {};
55   appInfo.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
56   appInfo.pApplicationName = "vulkanExample";
57   appInfo.pEngineName = "vulkanExample";
58   appInfo.apiVersion = VK_API_VERSION_1_3;
59
60   VkInstanceCreateInfo instanceCreateInfo = {};
61   instanceCreateInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
62   instanceCreateInfo.pNext = NULL;
63   instanceCreateInfo.pApplicationInfo = &appInfo;
64
65   std::vector<const char *> instanceExtensions = {
66       VK_KHR_SURFACE_EXTENSION_NAME,
67       VK_OHOS_SURFACE_EXTENSION_NAME // Surface extension.
68   };
69   instanceCreateInfo.enabledExtensionCount = static_cast<uint32_t>(instanceExtensions.size());
70   instanceCreateInfo.ppEnabledExtensionNames = instanceExtensions.data();
71
72   vkCreateInstance(&instanceCreateInfo, nullptr, &instance);
73   ```
74
752. Obtain an **OHNativeWindow** instance.
76
77   The **OHNativeWindow** instance is obtained from the **XComponent**. For details about how to use the **XComponent**, see [Custom Rendering (XComponent)](../../ui/napi-xcomponent-guidelines.md).
78
79   1. Add an **XComponent** to **ets/pages/Index.ets**.
80
81      ```ts
82      XComponent({
83          id: 'xcomponentId',
84          type: 'surface',
85          libraryname: 'entry'
86      })
87      .margin({ bottom: 20 })
88      .width(360)
89      .height(360)
90      ```
91
92   2. Obtain an **OHNativeWindow** instance from the **XComponent**.
93
94      ```c++
95      // Callback function of the XComponent triggered when a surface is created.
96      void OnSurfaceCreatedCB(OH_NativeXComponent *component, void *window) {
97          // You can obtain an OHNativeWindow instance from the callback function.
98          OHNativeWindow *nativeWindow = static_cast<OHNativeWindow *>(window);
99      }
100
101      static napi_value Init(napi_env env, napi_value exports) {
102          napi_property_descriptor desc[] = {{"add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr}};
103          napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
104
105          napi_value exportInstance = nullptr;
106          OH_NativeXComponent *nativeXComponent = nullptr;
107          // Obtain a native XComponent.
108          napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
109          napi_unwrap(env, exportInstance, reinterpret_cast<void **>(&nativeXComponent));
110          // Obtain the XComponent ID.
111          char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {};
112          uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
113          OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize);
114
115          // Declare an XComponent callback.
116          OH_NativeXComponent_Callback callback;
117          // Register the OnSurfaceCreated callback function.
118          callback.OnSurfaceCreated = OnSurfaceCreatedCB;
119          // Register the callback function for the native XComponent.
120          OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback);
121
122          return exports;
123      }
124      ```
125
1263. Create a **VkSurfaceKHR** instance.
127
128   ```c++
129   VkSurfaceKHR surface = VK_NULL_HANDLE;
130   VkSurfaceCreateInfoOHOS surfaceCreateInfo = {};
131   surfaceCreateInfo.sType = VK_STRUCTURE_TYPE_SURFACE_CREATE_INFO_OHOS;
132   surfaceCreateInfo.window = nativeWindow; // nativeWindow is obtained from the OnSurfaceCreatedCB callback function in the previous step.
133   int err = vkCreateSurfaceOHOS(instance, &surfaceCreateInfo, NULL, &surface);
134   if (err != VK_SUCCESS) {
135       // Creating the surface failed.
136   }
137   ```
138
139For details about how to use Vulkan, visit the [Vulkan official website](https://www.vulkan.org/).
140