!23379 【4.0Beta2】fix docs

Merge pull request !23379 from shegangbin/cherry-pick-1693296425

zh-cn/application-dev/napi/native-buffer-guidelines.md

@@ -39,6 +39,8 @@ libnative_buffer.so
 
 1. **创建OH_NativeBuffer实例**。
     ```c++
+    #include <iostream>
+
     OH_NativeBuffer_Config config {
         .width = 0x100,
         .height = 0x100,
@@ -69,8 +71,8 @@ libnative_buffer.so
 3. **获取内存的属性信息**。
     ```c++
     // 获取OH_NativeBuffer的属性
-    OH_NativeBuffer_Config config = {};
-    OH_NativeBuffer_GetConfig(buffer, &config);
+    OH_NativeBuffer_Config config2 = {};
+    OH_NativeBuffer_GetConfig(buffer, &config2);
     // 获取OH_NativeBuffer的序列号
      uint32_t hwBufferID = OH_NativeBuffer_GetSeqNum(buffer);
     ```

zh-cn/application-dev/napi/native-image-guidelines.md

@@ -51,8 +51,11 @@ libnative_buffer.so
 
     这里提供一份初始化EGL环境的代码示例
     ```c++
+    #include <iostream>
+    #include <string>
     #include <EGL/egl.h>
     #include <EGL/eglext.h>
+
     using GetPlatformDisplayExt = PFNEGLGETPLATFORMDISPLAYEXTPROC;
     constexpr const char* EGL_EXT_PLATFORM_WAYLAND = "EGL_EXT_platform_wayland";
     constexpr const char* EGL_KHR_PLATFORM_WAYLAND = "EGL_KHR_platform_wayland";
@@ -167,7 +170,15 @@ libnative_buffer.so
     OHNativeWindow* nativeWindow = OH_NativeImage_AcquireNativeWindow(image);
     ```
 
-4. **将生产的内容写入NativeWindowBuffer**。
+4. **设置NativeWindow的宽高**。
+    ```c++
+    int code = SET_BUFFER_GEOMETRY;
+    int32_t width = 800;
+    int32_t height = 600;
+    int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height);
+    ```
+
+5. **将生产的内容写入NativeWindowBuffer**。
     1. 从NativeWindow中获取NativeWindowBuffer
     ```c++
     OHNativeWindowBuffer* buffer = nullptr;
@@ -176,38 +187,46 @@ libnative_buffer.so
     OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow, &buffer, &fenceFd);
     
     BufferHandle *handle = OH_NativeWindow_GetBufferHandleFromNative(buffer);
-    int code = SET_BUFFER_GEOMETRY;
-    int32_t width = 0x100;
-    int32_t height = 0x100;
-    ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height);
     ```
-    3. 将生产的内容写入NativeWindowBuffer
+    2. 将生产的内容写入NativeWindowBuffer
     ```c++
+    #include <sys/mman.h>
+    
+    // 使用系统mmap接口拿到bufferHandle的内存虚拟地址
+    void* mappedAddr = mmap(handle->virAddr, handle->size, PROT_READ | PROT_WRITE, MAP_SHARED, handle->fd, 0);
+    if (mappedAddr == MAP_FAILED) {
+        // mmap failed
+    }
     static uint32_t value = 0x00;
     value++;
-    uint32_t *pixel = static_cast<uint32_t *>(handle->virAddr);
+    uint32_t *pixel = static_cast<uint32_t *>(mappedAddr);
     for (uint32_t x = 0; x < width; x++) {
         for (uint32_t y = 0;  y < height; y++) {
             *pixel++ = value;
         }
     }
+    // 内存使用完记得去掉内存映射
+    int result = munmap(mappedAddr, handle->size);
+    if (result == -1) {
+        // munmap failed
+    }
     ```
-    4. 将NativeWindowBuffer提交到NativeWindow
+    3. 将NativeWindowBuffer提交到NativeWindow
     ```c++
     // 设置刷新区域，如果Region中的Rect为nullptr,或者rectNumber为0，则认为NativeWindowBuffer全部有内容更改。
     Region region{nullptr, 0};
     // 通过OH_NativeWindow_NativeWindowFlushBuffer 提交给消费者使用，例如：显示在屏幕上。
     OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow, buffer, fenceFd, region);
     ```
-    5. 用完需要销毁NativeWindow
+    4. 用完需要销毁NativeWindow
     ```c++
     OH_NativeWindow_DestroyNativeWindow(nativeWindow);
     ```
 
-5. **更新内容到OpenGL纹理**。
+6. **更新内容到OpenGL纹理**。
     ```c++
     // 更新内容到OpenGL纹理。
-    int32_t ret = OH_NativeImage_UpdateSurfaceImage(image);
+    ret = OH_NativeImage_UpdateSurfaceImage(image);
     if (ret != 0) {
         std::cout << "OH_NativeImage_UpdateSurfaceImage failed" << std::endl;
     }
@@ -220,7 +239,7 @@ libnative_buffer.so
     }
     ```
 
-6. **解绑OpenGL纹理，绑定到新的外部纹理上**。
+7. **解绑OpenGL纹理，绑定到新的外部纹理上**。
     ```c++
     // 将OH_NativeImage实例从当前OpenGL ES上下文分离
     ret = OH_NativeImage_DetachContext(image);
@@ -233,7 +252,7 @@ libnative_buffer.so
     ret = OH_NativeImage_AttachContext(image, textureId2);
     ```
 
-7. **OH_NativeImage实例使用完需要销毁掉**。
+8. **OH_NativeImage实例使用完需要销毁掉**。
     ```c++
     // 销毁OH_NativeImage实例
     OH_NativeImage_Destroy(&image);

zh-cn/application-dev/napi/native-vsync-guidelines.md

@@ -33,6 +33,8 @@ libnative_vsync.so
 
 1. **首先需要准备一个VSync回调函数**
     ```c++
+    #include <iostream>
+
     static bool flag = false;
     static void OnVSync(long long timestamp, void* data)
     {
@@ -49,6 +51,9 @@ libnative_vsync.so
 
 3. **通过OH_NativeVsync实例设置VSync回调函数**。
     ```c++
+    #include <unistd.h>
+    #include <iostream>
+
     OH_NativeVSync_RequestFrame(nativeVSync, callback, nullptr);
     while (!flag) { // 判断flag值，上面的VSync回调函数被执行后才会跳出while循环，表示已经接收到VSync信号
         std::cout << "wait for vsync!\n";

zh-cn/application-dev/napi/native-window-guidelines.md

@@ -53,6 +53,10 @@ libnative_window.so
         OH_NativeXComponent *nativeXComponent = nullptr;
         // 通过napi_unwrap接口，解析出NativeXComponent的实例指针
         napi_unwrap(env, exportInstance, reinterpret_cast<void**>(&nativeXComponent));
+        // 获取XComponentId
+        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。
         ```c++
@@ -104,10 +108,6 @@ libnative_window.so
     int32_t height = 0x100;
     // 这里的nativeWindow是从上一步骤中的回调函数中获得的
     int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height);
-    // 设置 OHNativeWindowBuffer 的步长
-    code = SET_STRIDE;
-    int32_t stride = 0x8;
-    ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, stride);
     ```
 
 3. **从图形队列申请OHNativeWindowBuffer**。

zh-cn/application-dev/napi/vulkan-guidelines.md

@@ -18,6 +18,11 @@ Vulkan是一套用来做2D和3D渲染的图形应用程序接口，其中创建V
 
 以下步骤说明了如何在OpenHarmony平台创建一个VkSurfaceKHR对象。
 
+首先，使用OpenHarmony平台扩展的接口，需要定义一个宏`VK_USE_PLATFORM_OHOS`，我们在CMakeLists.txt定义这个宏。
+```txt
+ADD_DEFINITIONS(-DVK_USE_PLATFORM_OHOS=1)
+```
+
 **添加动态链接库**
 
 CMakeLists.txt中添加以下lib。
@@ -80,7 +85,6 @@ libvulkan.so
         OHNativeWindow* nativeWindow = static_cast<OHNativeWindow*>(window);
     }
 
-    EXTERN_C_START
     static napi_value Init(napi_env env, napi_value exports)
     {
         napi_property_descriptor desc[] = {
@@ -88,18 +92,20 @@ libvulkan.so
         };
         napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
 
-        // 声明一个XComponent的Callback
-        OH_NativeXComponent_Callback callback;
-        // 注册OnSurfaceCreated回调函数
-        callback.OnSurfaceCreated = OnSurfaceCreatedCB;
-        
-        char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {};
-        uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
         napi_value exportInstance = nullptr;
         OH_NativeXComponent *nativeXComponent = nullptr;
         // 获取nativeXComponent
         napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &exportInstance);
         napi_unwrap(env, exportInstance, reinterpret_cast<void **>(&nativeXComponent));
+        // 获取XComponentId
+        char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = {};
+        uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1;
+        OH_NativeXComponent_GetXComponentId(nativeXComponent, idStr, &idSize);
+
+        // 声明一个XComponent的Callback
+        OH_NativeXComponent_Callback callback;
+        // 注册OnSurfaceCreated回调函数
+        callback.OnSurfaceCreated = OnSurfaceCreatedCB;
         // 将callback注册给nativeXComponent
         OH_NativeXComponent_RegisterCallback(nativeXComponent, &callback);
         
@@ -115,7 +121,7 @@ libvulkan.so
     surfaceCreateInfo.window = nativeWindow; // 这里的nativeWindow就是从上一步骤OnSurfaceCreatedCB回调函数中拿到的
     int err = vkCreateSurfaceOHOS(instance, &surfaceCreateInfo, NULL, &surface);
     if (err != VK_SUCCESS) {
-        std::cout << "Could not create surface!" << std::endl;
+        // Create Surface Failed.
     }
     ```
 后续更多vulkan的用法请参考[Vulkan官方网站](https://www.vulkan.org/)。