1# NativeImage开发指导 (C/C++) 2 3## 场景介绍 4 5NativeImage是提供**Surface关联OpenGL外部纹理**的模块，表示图形队列的消费者端。开发者可以通过`NativeImage`接口接收和使用`Buffer`，并将`Buffer`关联输出到OpenGL外部纹理。 6针对NativeImage，常见的开发场景如下： 7 8* 通过`NativeImage`提供的Native API接口创建`NativeImage`实例作为消费者端，获取与该实例对应的`NativeWindow`作为生产者端。`NativeWindow`相关接口可用于填充`Buffer`内容并提交，`NativeImage`将`Buffer`内容更新到OpenGL外部纹理上。本模块需要配合NativeWindow、NativeBuffer、EGL、GLES3模块一起使用。 9 10## 接口说明 11 12| 接口名 | 描述 | 13| ------------------------------------------------------------ | ------------------------------------------------------------ | 14| OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget) | 创建一个OH_NativeImage实例，该实例与OpenGL ES的纹理ID和纹理目标相关联。 | 15| OH_NativeImage_AcquireNativeWindow (OH_NativeImage \*image) | 获取与OH_NativeImage相关联的OHNativeWindow指针，该OHNativeWindow后续不再需要时需要调用 OH_NativeWindow_DestroyNativeWindow释放。 | 16| OH_NativeImage_AttachContext (OH_NativeImage \*image, uint32_t textureId) | 将OH_NativeImage实例附加到当前OpenGL ES上下文，且该OpenGL ES纹理会绑定到 GL_TEXTURE_EXTERNAL_OES，并通过OH_NativeImage进行更新。 | 17| OH_NativeImage_DetachContext (OH_NativeImage \*image) | 将OH_NativeImage实例从当前OpenGL ES上下文分离。 | 18| OH_NativeImage_UpdateSurfaceImage (OH_NativeImage \*image) | 通过OH_NativeImage获取最新帧更新相关联的OpenGL ES纹理。 | 19| OH_NativeImage_GetTimestamp (OH_NativeImage \*image) | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的相关时间戳。 | 20| OH_NativeImage_GetTransformMatrix (OH_NativeImage \*image, float matrix[16]) | 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的变化矩阵。 | 21| OH_NativeImage_Destroy (OH_NativeImage \*\*image) | 销毁通过OH_NativeImage_Create创建的OH_NativeImage实例，销毁后该OH_NativeImage指针会被赋值为空。 | 22 23详细的接口说明请参考[native_image](../reference/apis-arkgraphics2d/_o_h___native_image.md)。 24 25## 开发步骤 26 27以下步骤描述了如何使用`NativeImage`提供的Native API接口，创建`OH_NativeImage`实例作为消费者端，将数据内容更新到OpenGL外部纹理上。 28 29**添加动态链接库** 30 31CMakeLists.txt中添加以下lib。 32 33```txt 34libEGL.so 35libGLESv3.so 36libnative_image.so 37libnative_window.so 38libnative_buffer.so 39``` 40 41**头文件** 42 43```c++ 44#include <EGL/egl.h> 45#include <EGL/eglext.h> 46#include <GLES3/gl3.h> 47#include <native_image/native_image.h> 48#include <native_window/external_window.h> 49#include <native_buffer/native_buffer.h> 50``` 51 521. **初始化EGL环境**。 53 54 这里提供一份初始化EGL环境的代码示例。XComponent模块的具体使用方法请参考[XComponent开发指导](../ui/napi-xcomponent-guidelines.md)。 55 ```c++ 56 #include <iostream> 57 #include <string> 58 #include <EGL/egl.h> 59 #include <EGL/eglext.h> 60 61 using GetPlatformDisplayExt = PFNEGLGETPLATFORMDISPLAYEXTPROC; 62 constexpr const char *EGL_EXT_PLATFORM_WAYLAND = "EGL_EXT_platform_wayland"; 63 constexpr const char *EGL_KHR_PLATFORM_WAYLAND = "EGL_KHR_platform_wayland"; 64 constexpr int32_t EGL_CONTEXT_CLIENT_VERSION_NUM = 2; 65 constexpr char CHARACTER_WHITESPACE = ' '; 66 constexpr const char *CHARACTER_STRING_WHITESPACE = " "; 67 constexpr const char *EGL_GET_PLATFORM_DISPLAY_EXT = "eglGetPlatformDisplayEXT"; 68 EGLContext eglContext_ = EGL_NO_CONTEXT; 69 EGLDisplay eglDisplay_ = EGL_NO_DISPLAY; 70 static inline EGLConfig config_; 71 static inline EGLSurface eglsurface_; 72 // 从XComponent中获取到的OHNativeWindow 73 OHNativeWindow *eglNativeWindow_; 74 75 // 检查egl扩展 76 static bool CheckEglExtension(const char *extensions, const char *extension) { 77 size_t extlen = strlen(extension); 78 const char *end = extensions + strlen(extensions); 79 80 while (extensions < end) { 81 size_t n = 0; 82 if (*extensions == CHARACTER_WHITESPACE) { 83 extensions++; 84 continue; 85 } 86 n = strcspn(extensions, CHARACTER_STRING_WHITESPACE); 87 if (n == extlen && strncmp(extension, extensions, n) == 0) { 88 return true; 89 } 90 extensions += n; 91 } 92 return false; 93 } 94 95 // 获取当前的显示设备 96 static EGLDisplay GetPlatformEglDisplay(EGLenum platform, void *native_display, const EGLint *attrib_list) { 97 static GetPlatformDisplayExt eglGetPlatformDisplayExt = NULL; 98 99 if (!eglGetPlatformDisplayExt) { 100 const char *extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); 101 if (extensions && (CheckEglExtension(extensions, EGL_EXT_PLATFORM_WAYLAND) || 102 CheckEglExtension(extensions, EGL_KHR_PLATFORM_WAYLAND))) { 103 eglGetPlatformDisplayExt = (GetPlatformDisplayExt)eglGetProcAddress(EGL_GET_PLATFORM_DISPLAY_EXT); 104 } 105 } 106 107 if (eglGetPlatformDisplayExt) { 108 return eglGetPlatformDisplayExt(platform, native_display, attrib_list); 109 } 110 111 return eglGetDisplay((EGLNativeDisplayType)native_display); 112 } 113 114 static void InitEGLEnv() { 115 // 获取当前的显示设备 116 eglDisplay_ = GetPlatformEglDisplay(EGL_PLATFORM_OHOS_KHR, EGL_DEFAULT_DISPLAY, NULL); 117 if (eglDisplay_ == EGL_NO_DISPLAY) { 118 std::cout << "Failed to create EGLDisplay gl errno : " << eglGetError() << std::endl; 119 } 120 121 EGLint major, minor; 122 // 初始化EGLDisplay 123 if (eglInitialize(eglDisplay_, &major, &minor) == EGL_FALSE) { 124 std::cout << "Failed to initialize EGLDisplay" << std::endl; 125 } 126 127 // 绑定图形绘制的API为OpenGLES 128 if (eglBindAPI(EGL_OPENGL_ES_API) == EGL_FALSE) { 129 std::cout << "Failed to bind OpenGL ES API" << std::endl; 130 } 131 132 unsigned int ret; 133 EGLint count; 134 EGLint config_attribs[] = {EGL_SURFACE_TYPE, 135 EGL_WINDOW_BIT, 136 EGL_RED_SIZE, 137 8, 138 EGL_GREEN_SIZE, 139 8, 140 EGL_BLUE_SIZE, 141 8, 142 EGL_ALPHA_SIZE, 143 8, 144 EGL_RENDERABLE_TYPE, 145 EGL_OPENGL_ES3_BIT, 146 EGL_NONE}; 147 148 // 获取一个有效的系统配置信息 149 ret = eglChooseConfig(eglDisplay_, config_attribs, &config_, 1, &count); 150 if (!(ret && static_cast<unsigned int>(count) >= 1)) { 151 std::cout << "Failed to eglChooseConfig" << std::endl; 152 } 153 154 static const EGLint context_attribs[] = {EGL_CONTEXT_CLIENT_VERSION, EGL_CONTEXT_CLIENT_VERSION_NUM, EGL_NONE}; 155 156 // 创建上下文 157 eglContext_ = eglCreateContext(eglDisplay_, config_, EGL_NO_CONTEXT, context_attribs); 158 if (eglContext_ == EGL_NO_CONTEXT) { 159 std::cout << "Failed to create egl context %{public}x, error:" << eglGetError() << std::endl; 160 } 161 162 // 创建eglSurface 163 eglSurface_ = eglCreateWindowSurface(eglDisplay_, config_, eglNativeWindow_, context_attribs); 164 if (eglSurface_ == EGL_NO_SURFACE) { 165 std::cout << "Failed to create egl surface %{public}x, error:" << eglGetError() << std::endl; 166 } 167 168 // 关联上下文 169 eglMakeCurrent(eglDisplay_, eglSurface_, eglSurface_, eglContext_); 170 171 // EGL环境初始化完成 172 std::cout << "Create EGL context successfully, version" << major << "." << minor << std::endl; 173 } 174 ``` 175 1762. **创建OH_NativeImage实例**。 177 178 ```c++ 179 // 创建 OpenGL 纹理 180 GLuint textureId; 181 glGenTextures(1, &textureId); 182 // 创建 NativeImage 实例，关联 OpenGL 纹理 183 OH_NativeImage* image = OH_NativeImage_Create(textureId, GL_TEXTURE_2D); 184 ``` 185 1863. **获取对应的数据生产者端NativeWindow**。 187 188 ```c++ 189 // 获取生产者NativeWindow 190 OHNativeWindow* nativeWindow = OH_NativeImage_AcquireNativeWindow(image); 191 ``` 192 1934. **设置NativeWindow的宽高**。 194 195 ```c++ 196 int code = SET_BUFFER_GEOMETRY; 197 int32_t width = 800; 198 int32_t height = 600; 199 int32_t ret = OH_NativeWindow_NativeWindowHandleOpt(nativeWindow, code, width, height); 200 ``` 201 2025. **将生产的内容写入NativeWindowBuffer**。 203 204 1. 从NativeWindow中获取NativeWindowBuffer。 205 206 ```c++ 207 OHNativeWindowBuffer *buffer = nullptr; 208 int fenceFd; 209 // 通过 OH_NativeWindow_NativeWindowRequestBuffer 获取 OHNativeWindowBuffer 实例 210 OH_NativeWindow_NativeWindowRequestBuffer(nativeWindow, &buffer, &fenceFd); 211 212 BufferHandle *handle = OH_NativeWindow_GetBufferHandleFromNative(buffer); 213 ``` 214 215 2. 将生产的内容写入NativeWindowBuffer。 216 217 ```c++ 218 #include <sys/mman.h> 219 220 // 使用系统mmap接口拿到bufferHandle的内存虚拟地址 221 void *mappedAddr = mmap(handle->virAddr, handle->size, PROT_READ | PROT_WRITE, MAP_SHARED, handle->fd, 0); 222 if (mappedAddr == MAP_FAILED) { 223 // mmap failed 224 } 225 static uint32_t value = 0x00; 226 value++; 227 uint32_t *pixel = static_cast<uint32_t *>(mappedAddr); 228 for (uint32_t x = 0; x < width; x++) { 229 for (uint32_t y = 0; y < height; y++) { 230 *pixel++ = value; 231 } 232 } 233 // 内存使用完记得去掉内存映射 234 int result = munmap(mappedAddr, handle->size); 235 if (result == -1) { 236 // munmap failed 237 } 238 ``` 239 240 3. 将NativeWindowBuffer提交到NativeWindow。 241 242 ```c++ 243 // 设置刷新区域，如果Region中的Rect为nullptr,或者rectNumber为0，则认为NativeWindowBuffer全部有内容更改。 244 Region region{nullptr, 0}; 245 // 通过OH_NativeWindow_NativeWindowFlushBuffer 提交给消费者使用，例如：显示在屏幕上。 246 OH_NativeWindow_NativeWindowFlushBuffer(nativeWindow, buffer, fenceFd, region); 247 ``` 248 249 4. 用完需要销毁NativeWindow。 250 251 ```c++ 252 OH_NativeWindow_DestroyNativeWindow(nativeWindow); 253 ``` 254 2556. **更新内容到OpenGL纹理**。 256 257 ```c++ 258 // 更新内容到OpenGL纹理。 259 ret = OH_NativeImage_UpdateSurfaceImage(image); 260 if (ret != 0) { 261 std::cout << "OH_NativeImage_UpdateSurfaceImage failed" << std::endl; 262 } 263 // 获取最近调用OH_NativeImage_UpdateSurfaceImage的纹理图像的时间戳和变化矩阵。 264 int64_t timeStamp = OH_NativeImage_GetTimestamp(image); 265 float matrix[16]; 266 ret = OH_NativeImage_GetTransformMatrix(image, matrix); 267 if (ret != 0) { 268 std::cout << "OH_NativeImage_GetTransformMatrix failed" << std::endl; 269 } 270 271 // 对update绑定到对应textureId的纹理做对应的opengl后处理后，将纹理上屏 272 EGLBoolean eglRet = eglSwapBuffers(eglDisplay_, eglSurface_); 273 if (eglRet == EGL_FALSE) { 274 std::cout << "eglSwapBuffers failed" << std::endl; 275 } 276 ``` 277 2787. **解绑OpenGL纹理，绑定到新的外部纹理上**。 279 280 ```c++ 281 // 将OH_NativeImage实例从当前OpenGL ES上下文分离 282 ret = OH_NativeImage_DetachContext(image); 283 if (ret != 0) { 284 std::cout << "OH_NativeImage_DetachContext failed" << std::endl; 285 } 286 // 将OH_NativeImage实例附加到当前OpenGL ES上下文, 且该OpenGL ES纹理会绑定到 GL_TEXTURE_EXTERNAL_OES, 并通过OH_NativeImage进行更新 287 GLuint textureId2; 288 glGenTextures(1, &textureId2); 289 ret = OH_NativeImage_AttachContext(image, textureId2); 290 ``` 291 2928. **OH_NativeImage实例使用完需要销毁掉**。 293 294 ```c++ 295 // 销毁OH_NativeImage实例 296 OH_NativeImage_Destroy(&image); 297 ``` 298 299## 相关实例 300 301针对NativeImage的开发，有以下相关实例可供参考： 302 303- [Native Window（API11）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Native/NdkNativeWindow)