1# 基于NdkNativeImage的平滑渐变动画效果 2 3### 介绍 4 5本示例主要演示如何在 OpenHarmony 系统中，使用 Native C++ 代码，通过 `OH_NativeImage`、`OH_NativeWindow` 和 `OH_NativeVSync` API，实现一个从左到右循环渐变的动态动画效果。示例展示了如何创建 `OH_NativeWindow` 实例、使用 `OH_NativeImage` 处理图像数据、接收 VSync 信号、映射缓冲区内存、逐像素绘制动态渐变动画，以及在屏幕上呈现该动画。 6 7### 效果预览 8 9| 动态渐变效果 | 10| -------------------------------------- | 11|  | 12 13### 使用说明 14 151. **编译安装**：使用 DevEco Studio 编译生成应用的 hap 包，并将其安装到设备上。 16 172. **运行应用**：打开应用后，您将看到屏幕上显示一个从左到右循环渐变的平滑动画效果。 18 19 20### 工程目录 21``` 22├──entry/src/main 23│ ├──cpp // C++代码区 24│ │ ├──CMakeLists.txt // CMake配置文件 25│ │ ├──napi_init.cpp // Napi模块注册 26│ │ ├──common 27│ │ │ └──common.h // 日志封装定义文件 28│ │ ├──render // 画面渲染模块 29│ │ │ ├──image_render.cpp // EGL相关进行处理 30│ │ │ ├──image_render.h 31│ │ │ ├──native_render.cpp // 生产画面内容 32│ │ │ ├──native_render.h 33│ │ │ ├──render_engine.cpp // 渲染引擎 34│ │ │ └──render_engine.h 35│ ├──ets // ets代码区 36│ │ ├──entryability 37│ │ │ ├──EntryAbility.ts // 程序入口类 38| | | └──EntryAbility.ets 39│ │ └──pages // 页面文件 40│ │ └──Index.ets // 主界面 41| ├──resources // 资源文件目录 42``` 43### 具体实现 44 45本示例通过在 DevEco Studio 中创建 Native C++ 工程，利用 `OH_NativeWindow`、`OH_NativeImage` 和 `OH_NativeVSync` API 直接操作像素数据，实现动态渐变动画。 46 47主要步骤如下： 48 491. **创建 RenderEngine**：`RenderEngine` 类负责渲染逻辑的管理，包括渲染线程的启动和停止，以及调用具体的渲染函数。 50 512. **获取窗口实例**：在 C++ 代码中，通过 Surface ID 获取 `OH_NativeWindow` 实例，用于与窗口系统交互。 52 533. **设置缓冲区属性**：使用 [`OH_NativeWindow_NativeWindowHandleOpt`](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkgraphics2d/_native_window.md#oh_nativewindow_nativewindowhandleopt) 函数设置缓冲区的大小、像素格式等属性，确保缓冲区满足渲染需求。 54 554. **创建 OH_NativeImage 实例**：使用 `OH_NativeImage_Create` 函数创建 `OH_NativeImage` 对象，用于处理图像数据。 56 575. **初始化 VSync**：使用 `OH_NativeVSync_Create` 函数创建 `OH_NativeVSync` 实例，接收 VSync 信号。 58 596. **请求缓冲区并映射内存**：使用 [`OH_NativeWindow_NativeWindowRequestBuffer`](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkgraphics2d/_native_window.md#oh_nativewindow_nativewindowrequestbuffer) 函数请求一个可写的缓冲区，然后使用 `mmap` 函数将缓冲区内存映射到虚拟地址空间，获取像素数据指针。 60 617. **渲染动态渐变**：在 `DrawGradient` 函数中，利用 `OH_NativeImage` 对象，对像素数据进行操作，使用余弦函数计算每个像素的颜色强度，实现从左到右的平滑渐变，并通过时间变量实现动画效果，使渐变循环移动。 62 638. **提交缓冲区**：渲染完成后，解除内存映射，并使用 [`OH_NativeWindow_NativeWindowFlushBuffer`](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkgraphics2d/_native_window.md#oh_nativewindow_nativewindowflushbuffer) 函数将缓冲区提交给消费者，刷新显示内容。 64 659. **启动渲染线程**：`RenderEngine` 类在后台启动一个渲染线程，持续调用 `RenderFrame` 函数，以固定的帧率（例如 120 FPS）更新动画。 66 6710. **停止渲染线程**：在适当的时候，调用 `RenderEngine` 类的 `Stop` 函数，停止渲染线程，释放资源。 68#### 涉及到的相关接口 69 70| 接口名 | 描述 | 71| -------- | -------- | 72| `OH_NativeWindow_CreateNativeWindowFromSurfaceId(uint64_t surfaceId, OHNativeWindow **window)` | 通过 Surface ID 创建 `OH_NativeWindow` 对象，用于显示图形内容。 | 73| `OH_NativeWindow_NativeWindowHandleOpt(OH_NativeWindow *window, int code, ...)` | 设置 `OH_NativeWindow` 的属性，例如缓冲区大小、像素格式等。 | 74| `OH_NativeWindow_NativeWindowRequestBuffer(OH_NativeWindow *window, OH_NativeWindow_Buffer **buffer, int *fenceFd)` | 请求一个可写的缓冲区，用于渲染内容。 | 75| `OH_NativeWindow_GetBufferHandleFromNative(OH_NativeWindow_Buffer *buffer)` | 从 `OH_NativeWindow_Buffer` 获取 `BufferHandle`，以便进行内存映射。 | 76| `OH_NativeWindow_NativeWindowFlushBuffer(OH_NativeWindow *window, OH_NativeWindow_Buffer *buffer, int fenceFd, Region region)` | 将渲染完成的缓冲区提交给消费者，刷新显示内容。 | 77| `OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget)` | 创建一个 `OH_NativeImage` 实例，绑定到指定的 OpenGL 纹理。 | 78| `OH_NativeImage_Destroy(OH_NativeImage **nativeImage)` | 销毁 `OH_NativeImage` 实例，释放资源。 | 79| `OH_NativeImage_GetSurfaceId(OH_NativeImage *nativeImage, uint64_t *surfaceId)` | 获取 `OH_NativeImage` 的显示标识符。 | 80| `OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage *nativeImage, OH_NativeImage_OnFrameAvailableListener listener)` | 设置帧可用监听器，当新帧可用时触发回调。 | 81| `OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage *nativeImage)` | 移除帧可用监听器。 | 82| `OH_NativeImage_UpdateSurfaceImage(OH_NativeImage *nativeImage)` | 更新 `OH_NativeImage` 对象的图像内容。 | 83| `OH_NativeImage_GetTransformMatrixV2(OH_NativeImage *nativeImage, float matrix[16])` | 获取 `OH_NativeImage` 的纹理变换矩阵。 | 84| `OH_NativeVSync_Create(const char* name, unsigned int length)` | 创建一个 `OH_NativeVSync` 实例，用于接收 VSync 信号。 | 85| `OH_NativeVSync_Destroy(OH_NativeVSync *vsync)` | 销毁 `OH_NativeVSync` 实例，释放资源。 | 86| `OH_NativeVSync_RequestFrame(OH_NativeVSync *vsync, OH_NativeVSync_OnVSync callback, void *data)` | 请求下一帧的 VSync 信号，注册回调函数。 | 87 88### 相关权限 89 90本示例不涉及特殊权限。 91 92### 依赖 93XComponent NativeWindow。 94### 约束与限制 95 961. **运行环境**：本示例仅支持在 OpenHarmony 标准系统上运行。 97 982. **SDK 版本**：本示例已适配 API Version 12 版本 SDK，适用于 SDK 版本号（API Version 12 Release）、镜像版本号（5.0.0 Release）。 99 1003. **开发工具**：本示例需要使用 DevEco Studio 版本号（5.0.0 Release）及以上版本进行编译和运行。 101 102### 下载 103 104如需单独下载本工程，执行如下命令： 105 106```bash 107git init 108git config core.sparsecheckout true 109echo code/BasicFeature/Native/NdkNativeImage > .git/info/sparse-checkout 110git remote add origin https://gitee.com/openharmony/applications_app_samples.git 111git pull origin master 112```
