• 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. Creating a **VkSurfaceKHR** instance is a key step, since **VkSurfaceKHR** work 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](../reference/native-lib/third_party_vulkan/vulkan-symbol.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```txt
23ADD_DEFINITIONS(-DVK_USE_PLATFORM_OHOS=1)
24```
25
26**Adding Dynamic Link Libraries**
27
28Add the following libraries to **CMakeLists.txt**:
29```txt
30libace_ndk.z.so
31libnative_window.so
32libvulkan.so
33```
34
35**Header File**
36```c++
37#include <ace/xcomponent/native_interface_xcomponent.h>
38#include <native_window/external_window.h>
39#include <vulkan/vulkan.h>
40```
41
421. Create a Vulkan instance.
43    ```c++
44    VkInstance instance = VK_NULL_HANDLE;
45
46    VkApplicationInfo appInfo = {};
47    appInfo.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
48    appInfo.pApplicationName = "vulkanExample";
49    appInfo.pEngineName = "vulkanExample";
50    appInfo.apiVersion = VK_API_VERSION_1_3;
51
52    VkInstanceCreateInfo instanceCreateInfo = {};
53    instanceCreateInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
54    instanceCreateInfo.pNext = NULL;
55    instanceCreateInfo.pApplicationInfo = &appInfo;
56
57    std::vector<const char*> instanceExtensions = {
58        VK_KHR_SURFACE_EXTENSION_NAME,
59        VK_OHOS_SURFACE_EXTENSION_NAME // Surface extension.
60    };
61    instanceCreateInfo.enabledExtensionCount = static_cast<uint32_t>(instanceExtensions.size());
62    instanceCreateInfo.ppEnabledExtensionNames = instanceExtensions.data();
63
64    vkCreateInstance(&instanceCreateInfo, nullptr, &instance);
65    ```
66
672. Obtain an **OHNativeWindow** instance.
68    The **OHNativeWindow** instance is obtained from the **\<XComponent>**. For details about how to use the **\<XComponent>**, see [XComponent](../ui/arkts-common-components-xcomponent.md) and [XComponent Development](xcomponent-guidelines.md).
69    1. Add an **\<XComponent>** to **ets/pages/Index.ets**.
70    ```ts
71    XComponent({
72        id: 'xcomponentId',
73        type: 'surface',
74        libraryname: 'entry'
75    })
76    .margin({ bottom: 20 })
77    .width(360)
78    .height(360)
79    ```
80    2. Obtain an **OHNativeWindow** instance from the **\<XComponent>**.
81    ```c++
82    // Callback function of the \<XComponent> triggered when a surface is created.
83    void OnSurfaceCreatedCB(OH_NativeXComponent *component, void *window) {
84        // You can obtain an OHNativeWindow instance from the callback function.
85        OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
86    }
87
88    static napi_value Init(napi_env env, napi_value exports)
89    {
90        napi_property_descriptor desc[] = {
91            { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr }
92        };
93        napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
94
95        napi_value exportInstance = nullptr;
96        OH_NativeXComponent *nativeXComponent = nullptr;
97        // Obtain a native XComponent.
98        napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
99        napi_unwrap(env, exportInstance, reinterpret_cast<void **>(&nativeXComponent));
100        // Obtain the XComponent ID.
101        char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {};
102        uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
103        OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize);
104
105        // Declare an XComponent callback.
106        OH_NativeXComponent_Callback callback;
107        // Register the OnSurfaceCreated callback function.
108        callback.OnSurfaceCreated = OnSurfaceCreatedCB;
109        // Register the callback function for the native XComponent.
110        OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback);
111
112        return exports;
113    }
114    ```
115
1163. Create a **VkSurfaceKHR** instance.
117    ```c++
118    VkSurfaceKHR surface = VK_NULL_HANDLE;
119    VkSurfaceCreateInfoOHOS surfaceCreateInfo = {};
120    surfaceCreateInfo.sType = VK_STRUCTURE_TYPE_SURFACE_CREATE_INFO_OHOS;
121    surfaceCreateInfo.window = nativeWindow; // nativeWindow is obtained from the OnSurfaceCreatedCB callback function in the previous step.
122    int err = vkCreateSurfaceOHOS(instance, &surfaceCreateInfo, NULL, &surface);
123    if (err != VK_SUCCESS) {
124        // // Creating the surface failed.
125    }
126    ```
127For details about how to use Vulkan, visit the [Vulkan official website](https://www.vulkan.org/).
128