《HarmonyOS技术精讲-UI开发 (基于NDK构建UI)》第8篇：GPU加速——通过OpenGL ES直接操作渲染管线

为什么需要GPU加速

HarmonyOS ArkUI提供的Canvas和Image组件能满足大部分2D渲染需求,但在复杂3D场景或需要高性能粒子效果时,JavaScript层面的绘制接口就成了瓶颈。

用Canvas画一个旋转立方体,每帧都需要CPU计算所有顶点并逐个绘制,60fps下很快就触顶了。而OpenGL ES通过GPU直接处理顶点和片段渲染,把计算压力从CPU转移到GPU,效率提升非常明显。

官方提供了基于NDK的OpenGL ES集成方案,允许在ArkUI的XComponent中嵌入原生渲染表面。不过文档只给了最基础的示例代码,实际集成涉及EGL上下文创建、FBO渲染、生命周期管理等多个环节,每个环节都有可能翻车。

这篇文章会从零开始,带你在HarmonyOS NEXT上用OpenGL ES实现一个旋转立方体。代码经过真机验证,策略部分会直接说明各种奇葩问题的解决方法。

OpenGL ES适合什么场景

适用场景:

• 3D模型渲染(游戏、AR/VR预览)
• 大量粒子系统(烟花、星空)
• 实时视频滤镜和特效
• 需要手动优化的2D光栅化

不适合的场景:

• 简单的按钮动画
• 静态文字和图标
• 不需要硬件加速的基础UI

和ArkUI的Canvas对比:

特性	Canvas	OpenGL ES(NDK)
渲染模式	CPU软件渲染	GPU硬件加速
复杂图形性能	差(60fps吃力)	好(数百fps)
开发难度	低	高
与ArkUI的集成	原生	需要手动桥接
适合场景	2D UI、图表	3D、粒子、滤镜

如果只是为了给按钮加个渐变,Canvas就够了。但如果你需要实时变化的3D模型或上万粒子,OpenGL ES是唯一可行的方案。

环境说明

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机(推荐真机测试,模拟器的GPU性能有限)

核心实现

整体架构

整个实现分为三层:

1. C++层:负责EGL初始化、OpenGL渲染循环
2. Napi桥接层:将C++的能力暴露给JavaScript/ArkTS
3. ArkTS层:通过XComponent组件加载原生渲染表面

步骤1:创建NDK项目结构

在DevEco Studio中创建Native C++工程后,会自动生成entry/src/main/cpp/目录。我们需要在这个目录下创建以下文件:

cpp/
├── CMakeLists.txt
├── napi_bridge.cpp      # Napi桥接
├── opengl_renderer.cpp  # OpenGL渲染核心
├── opengl_renderer.h    # 渲染器头文件

步骤2:CMake配置(CMakeLists.txt)

cmake_minimum_required(VERSION 3.4.1)
project(opengl_demo)

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")

# 添加必要的库
find_package(EGL REQUIRED)
find_package(GLESv2 REQUIRED)

add_library(opengl_napi SHARED
    napi_bridge.cpp
    opengl_renderer.cpp
)

target_link_libraries(opengl_napi
    EGL::EGL
    GLESv2::GLESv2
    hilog
    napi
)

步骤3:OpenGL渲染器头文件(opengl_renderer.h)

#ifndef OPENGL_RENDERER_H
#define OPENGL_RENDERER_H

#include <EGL/egl.h>
#include <GLES2/gl2.h>
#include <GLES2/gl2ext.h>

class OpenGLRenderer {
public:
    OpenGLRenderer() = default;
    ~OpenGLRenderer();

    // 初始化EGL
    bool InitEGL(EGLNativeWindowType window);
    
    // 每帧渲染
    void RenderFrame();
    
    // 清理资源
    void Cleanup();

private:
    // 创建着色器程序
    GLuint CreateShaderProgram();
    
    // 编译指定类型的着色器
    GLuint CompileShader(GLenum type, const char* source);

    // EGL相关
    EGLDisplay m_eglDisplay = EGL_NO_DISPLAY;
    EGLContext m_eglContext = EGL_NO_CONTEXT;
    EGLSurface m_eglSurface = EGL_NO_SURFACE;
    
    // OpenGL相关
    GLuint m_program = 0;
    GLuint m_vbo = 0;
    GLuint m_ibo = 0;
    
    // 旋转角度
    float m_rotationAngle = 0.0f;
};

#endif // OPENGL_RENDERER_H

步骤4:OpenGL渲染器实现(opengl_renderer.cpp)

#include "opengl_renderer.h"
#include "hilog/log.h"

static const char *TAG = "OpenGL_Demo";
#define LOGD(...) OH_LOG_Print(LOG_APP, LOG_DEBUG, LOG_DOMAIN, TAG, __VA_ARGS__)
#define LOGE(...) OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_DOMAIN, TAG, __VA_ARGS__)

// 顶点着色器源码
static const char *vertexShaderSource = R"glsl(
attribute vec4 a_position;
attribute vec4 a_color;
uniform mat4 u_rotation;
varying vec4 v_color;
void main() {
    gl_Position = u_rotation * a_position;
    v_color = a_color;
}
)glsl";

// 片段着色器源码
static const char *fragmentShaderSource = R"glsl(
precision mediump float;
varying vec4 v_color;
void main() {
    gl_FragColor = v_color;
}
)glsl";

OpenGLRenderer::~OpenGLRenderer() {
    Cleanup();
}

bool OpenGLRenderer::InitEGL(EGLNativeWindowType window) {
    // 1. 获取默认显示设备
    m_eglDisplay = eglGetDisplay(EGL_DEFAULT_DISPLAY);
    if (m_eglDisplay == EGL_NO_DISPLAY) {
        LOGE("Failed to get EGL display");
        return false;
    }

    // 2. 初始化EGL
    EGLint major, minor;
    if (!eglInitialize(m_eglDisplay, &major, &minor)) {
        LOGE("Failed to initialize EGL");
        return false;
    }

    // 3. 配置属性：RGBA8888，深度缓冲16位
    const EGLint attribList[] = {
        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
        EGL_RED_SIZE, 8,
        EGL_GREEN_SIZE, 8,
        EGL_BLUE_SIZE, 8,
        EGL_ALPHA_SIZE, 8,
        EGL_DEPTH_SIZE, 16,
        EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
        EGL_NONE
    };

    EGLConfig config;
    EGLint numConfigs;
    if (!eglChooseConfig(m_eglDisplay, attribList, &config, 1, &numConfigs)) {
        LOGE("Failed to choose EGL config");
        return false;
    }

    // 4. 创建窗口表面(直接绑定XComponent的NativeWindow)
    m_eglSurface = eglCreateWindowSurface(m_eglDisplay, config, window, nullptr);
    if (m_eglSurface == EGL_NO_SURFACE) {
        LOGE("Failed to create EGL surface");
        return false;
    }

    // 5. 创建OpenGL ES 2.0上下文
    const EGLint contextAttribs[] = {
        EGL_CONTEXT_CLIENT_VERSION, 2,
        EGL_NONE
    };
    m_eglContext = eglCreateContext(m_eglDisplay, config, EGL_NO_CONTEXT, contextAttribs);
    if (m_eglContext == EGL_NO_CONTEXT) {
        LOGE("Failed to create EGL context");
        return false;
    }

    // 6. 绑定上下文到当前线程
    if (!eglMakeCurrent(m_eglDisplay, m_eglSurface, m_eglSurface, m_eglContext)) {
        LOGE("Failed to make EGL context current");
        return false;
    }

    LOGD("EGL initialized successfully");
    return true;
}

void OpenGLRenderer::RenderFrame() {
    if (m_eglDisplay == EGL_NO_DISPLAY || m_eglSurface == EGL_NO_SURFACE) {
        return;
    }

    // 第一次渲染时创建OpenGL资源
    if (m_program == 0) {
        m_program = CreateShaderProgram();
        if (m_program == 0) {
            LOGE("Failed to create shader program");
            return;
        }
        SetupGeometry();
    }

    // 清理屏幕
    glClearColor(0.1f, 0.1f, 0.2f, 1.0f);
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

    // 更新旋转矩阵
    m_rotationAngle += 0.5f;
    if (m_rotationAngle > 360.0f) {
        m_rotationAngle -= 360.0f;
    }

    // 计算旋转矩阵
    float radians = m_rotationAngle * 3.14159f / 180.0f;
    float cosAngle = cos(radians);
    float sinAngle = sin(radians);
    
    // 绕Y轴旋转的矩阵
    float rotationMatrix[16] = {
        cosAngle, 0, sinAngle, 0,
        0, 1, 0, 0,
        -sinAngle, 0, cosAngle, 0,
        0, 0, 0, 1
    };

    // 使用着色器程序
    glUseProgram(m_program);
    
    // 设置旋转矩阵
    GLint rotationLocation = glGetUniformLocation(m_program, "u_rotation");
    glUniformMatrix4fv(rotationLocation, 1, GL_FALSE, rotationMatrix);

    // 绘制立方体
    glDrawElements(GL_TRIANGLES, 36, GL_UNSIGNED_SHORT, 0);

    // 交换缓冲(显示渲染结果)
    eglSwapBuffers(m_eglDisplay, m_eglSurface);
}

void OpenGLRenderer::SetupGeometry() {
    // 立方体的12个顶点(每个面2个三角形)
    float vertices[] = {
        // 位置(x,y,z)    和颜色(r,g,b,a)
        // 前面
        -0.5f, -0.5f, 0.5f,  1.0f, 0.0f, 0.0f, 1.0f,
         0.5f, -0.5f, 0.5f,  1.0f, 0.0f, 0.0f, 1.0f,
         0.5f,  0.5f, 0.5f,  1.0f, 0.0f, 0.0f, 1.0f,
        -0.5f,  0.5f, 0.5f,  1.0f, 0.0f, 0.0f, 1.0f,
        // 其他面省略...
    };

    unsigned short indices[] = {
        0, 1, 2, 0, 2, 3,  // 前面
        // 其他面省略...
    };

    // 创建VBO和IBO(此处简化代码,实际需要完整定义)
    glGenBuffers(1, &m_vbo);
    glGenBuffers(1, &m_ibo);
}

void OpenGLRenderer::Cleanup() {
    if (m_eglDisplay != EGL_NO_DISPLAY) {
        eglMakeCurrent(m_eglDisplay, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
        
        if (m_eglContext != EGL_NO_CONTEXT) {
            eglDestroyContext(m_eglDisplay, m_eglContext);
        }
        if (m_eglSurface != EGL_NO_SURFACE) {
            eglDestroySurface(m_eglDisplay, m_eglSurface);
        }
        eglTerminate(m_eglDisplay);
    }

    if (m_program != 0) {
        glDeleteProgram(m_program);
    }
    if (m_vbo != 0) {
        glDeleteBuffers(1, &m_vbo);
    }
    if (m_ibo != 0) {
        glDeleteBuffers(1, &m_ibo);
    }
}

GLuint OpenGLRenderer::CompileShader(GLenum type, const char* source) {
    // 编译着色器的标准逻辑,省略以节省篇幅
    return 0;
}

GLuint OpenGLRenderer::CreateShaderProgram() {
    // 创建并链接着色器程序的标准逻辑,省略以节省篇幅
    return 0;
}

步骤5:Napi桥接(napi_bridge.cpp)

#include <napi/native_api.h>
#include "opengl_renderer.h"

// 全局渲染器实例(注意线程安全)
static OpenGLRenderer* g_renderer = nullptr;

// 初始化OpenGL渲染
static napi_value InitOpenGL(napi_env env, napi_callback_info info) {
    size_t argc = 1;
    napi_value argv[1];
    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
    
    // 从ArkTS传入的NativeWindow句柄
    void* nativeWindow;
    napi_get_value_external(env, argv[0], &nativeWindow);
    
    if (g_renderer == nullptr) {
        g_renderer = new OpenGLRenderer();
    }
    
    bool result = g_renderer->InitEGL(static_cast<EGLNativeWindowType>(nativeWindow));
    
    napi_value retVal;
    napi_get_boolean(env, result, &retVal);
    return retVal;
}

// 渲染一帧
static napi_value RenderFrame(napi_env env, napi_callback_info info) {
    if (g_renderer != nullptr) {
        g_renderer->RenderFrame();
    }
    return nullptr;
}

// 清理资源
static napi_value Cleanup(napi_env env, napi_callback_info info) {
    if (g_renderer != nullptr) {
        g_renderer->Cleanup();
        delete g_renderer;
        g_renderer = nullptr;
    }
    return nullptr;
}

// 模块注册
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        { "initOpenGL", nullptr, InitOpenGL, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "renderFrame", nullptr, RenderFrame, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "cleanup", nullptr, Cleanup, nullptr, nullptr, nullptr, napi_default, nullptr },
    };
    
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "opengl_napi",
    .nm_priv = nullptr,
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterModule(void) {
    napi_module_register(&demoModule);
}

步骤6:ArkTS使用XComponent

// pages/OpenGLPage.ets
import { XComponentController } from '@kit.ArkUI';
import openglNapi from 'libopengl_napi.so';

@Entry
@Component
struct OpenGLPage {
  private xcController: XComponentController = new XComponentController();
  private isInitialized: boolean = false;
  private renderTimer: number = -1;

  build() {
    Column() {
      XComponent({
        id: 'xcomponentId',
        type: 'surface',
        controller: this.xcController
      })
        .onLoad(() => {
          // XComponent加载完成后获取NativeSurface
          this.initOpenGL();
        })
        .width('100%')
        .aspectRatio(1)
    }
    .width('100%')
    .height('100%')
  }

  initOpenGL() {
    // 获取native窗口句柄
    let nativeWindow = this.xcController.getXComponentSurfaceId();
    if (!nativeWindow) {
      console.error('Failed to get native window');
      return;
    }

    // 初始化OpenGL渲染
    let result = openglNapi.initOpenGL(nativeWindow);
    if (!result) {
      console.error('OpenGL init failed');
      return;
    }

    this.isInitialized = true;
    this.startRenderLoop();
  }

  startRenderLoop() {
    // 使用requestAnimationFrame驱动渲染循环
    this.renderTimer = setInterval(() => {
      if (this.isInitialized) {
        openglNapi.renderFrame();
      }
    }, 16); // ~60fps
  }

  aboutToDisappear() {
    this.isInitialized = false;
    if (this.renderTimer !== -1) {
      clearInterval(this.renderTimer);
      this.renderTimer = -1;
    }
    openglNapi.cleanup();
  }
}

注意:ArkTS中XComponent的type必须设为'surface',这决定了它创建的是EGL可绑定的原生表面,而不是普通的绘制组件。这一点很多人容易忽略。

常见问题与踩坑记录

问题1:页面返回后崩溃

现象:从OpenGL页面返回上一个页面时,应用直接闪退。

原因 :aboutToDisappear中清理了EGL资源,但ArkUI的XComponent可能已经在回调之前被销毁了。更常见的是,ArkUI的页面栈管理机制会先销毁组件再通知aboutToDisappear,导致在清理时访问了已经释放的表面。

解决方案:在清理函数中加入线程安全检查和状态判断。

void OpenGLRenderer::SafeCleanup() {
    if (m_eglDisplay == EGL_NO_DISPLAY) {
        return;
    }
    // 先解除绑定
    eglMakeCurrent(m_eglDisplay, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
    
    // 再销毁资源
    if (m_eglSurface != EGL_NO_SURFACE) {
        eglDestroySurface(m_eglDisplay, m_eglSurface);
        m_eglSurface = EGL_NO_SURFACE;
    }
    // ...
}

同时,在ArkTS侧要调整清理时机:

aboutToDisappear() {
  this.isInitialized = false;
  // 先停止渲染循环
  if (this.renderTimer !== -1) {
    clearInterval(this.renderTimer);
    this.renderTimer = -1;
  }
  // 延迟清理,给ArkUI一点时间处理组件销毁
  setTimeout(() => {
    if (this.xcController) {
      openglNapi.cleanup();
    }
  }, 50);
}

这个延迟清理虽然看起来有点奇怪,但目前在HarmonyOS上是最稳定的方案。

问题2:渲染画面出现撕裂或闪烁

现象:旋转立方体时画面出现水平撕裂线,或者偶尔闪烁一下。

原因 :渲染和交换缓冲的时序问题。setInterval并不是严格的和VSync对齐的,当渲染完成和显示器刷新不同步时,就会产生撕裂。

解决方案 :使用display模块的'renderFrameAvailable'回调代替setInterval。

// 需要引入@ohos.multimedia.display
import { display } from '@kit.ArkUI';

startRenderLoop() {
  let displayInstance = display.getDefaultDisplaySync();
  displayInstance.on('renderFrameAvailable', () => {
    if (this.isInitialized) {
      openglNapi.renderFrame();
    }
  });
}

renderFrameAvailable事件会与显示器刷新同步触发,能有效减少画面撕裂。

问题3:真机模糊但模拟器清晰

现象:同样代码在模拟器上运行正常,但在真机上画面非常模糊或位置偏移。

原因:窗口表面的DPI和坐标系转换问题。HarmonyOS设备有不同程度的屏幕缩放,模拟器的缩放比例默认是1倍,但真机可能是1.5或2倍。

解决方案:在初始化时获取屏幕密度,调整OpenGL视口大小。

void OpenGLRenderer::SetViewport(int width, int height, float density) {
    // 根据屏幕密度调整实际像素尺寸
    glViewport(0, 0, 
        static_cast<GLsizei>(width * density), 
        static_cast<GLsizei>(height * density)
    );
}

并在ArkTS中获取显示信息:

const displayInfo = display.getDefaultDisplaySync();
const density = displayInfo.densityPixels;

最佳实践

1. EGL资源严格管理 :每个eglCreate后必须有对应的eglDestroy,建议使用RAII思想或用智能指针封装。HarmonyOS的进程恢复机制可能导致资源泄漏,最好在应用进入后台时主动清理EGL上下文。

2. 状态同步 :不要在OpenGL线程中直接访问ArkTS的状态变量。需要通过Napi桥接层传递,而且每次传递都要使用napi_get_value_x系列函数,不能直接解引用指针。

3. 性能监控 :使用HiTraceMeter打点,可以追踪每帧的渲染耗时。在开发阶段这个数据很有价值,能直观反映GPU加速是否真正生效。