HarmonyOS 鸿蒙Next自定义渲染（XComponent）入门介绍

1. 背景说明

HarmonyOS平台视频开发过程中，难免有自定义视频处理的需求，如直播美颜等等。本文章是关于自定义渲染 (XComponent)的流程梳理。

2. EGL（画布）

EGL是Embedded Graphics Library的缩写，可以翻译为嵌入式图形接口库，主要作用是连接 OpenGL/OpenGL ES 渲染 API 与操作系统原生窗口系统 的核心中间层。

EGL初始化主要包括三个步骤：

1） 获取EGLDisplay，用于连接本地窗口系统。

m_eglDisplay = eglGetDisplay(EGL_DEFAULT_DISPLAY);

2） 初始化EGL，主要检查 m_eglDisplay是否有效，并加载 EGL 库（如 libEGL.so）及其依赖的图形驱动。

EGLint majorVersion;
EGLint minorVersion;
int i_err = eglInitialize(m_eglDisplay, &majorVersion, &minorVersion)

3） 选择设备适合的EGLConfig

const EGLint ATTRIB_LIST[] = {
    EGL_SURFACE_TYPE, EGL_WINDOW_BIT,  // 支持窗口渲染
    EGL_RED_SIZE, 8,                   // 红色通道8位
    EGL_GREEN_SIZE, 8,                 // 绿色通道8位
    EGL_BLUE_SIZE, 8,                  // 蓝色通道8位
    EGL_ALPHA_SIZE, 8,                 // Alpha通道8位（可选）
    EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, // 支持 OpenGL ES 2.0
    EGL_NONE                           // 结束标记
};

// 选择EGLConfig.
const EGLint maxConfigSize = 1;//只选择符合条件中优先级最高的一个配置
EGLint numConfigs;//符合条件的配置数，若没有匹配的，返回0。
if (!eglChooseConfig(m_eglDisplay, ATTRIB_LIST, &m_eglConfig, maxConfigSize, &numConfigs))
{
    //错误处理
}

4） 创建EGL上下文

const EGLint CONTEXT_ATTRIBS[] = {EGL_CONTEXT_CLIENT_VERSION, 2, EGL_NONE};//指定 OpenGL ES 版本为 2.0
m_eglContext = eglCreateContext(m_eglDisplay, 
                                m_eglConfig, 
                                EGL_NO_CONTEXT, //不共享上下文
                                CONTEXT_ATTRIBS);

5） 创建EGL 离屏渲染表面，主要用于在HarmonyOS（HarmonyOS）平台上创建一个离屏的 EGLSurface，用于 ​后台渲染​（如滤镜处理、图像合成等不直接显示到屏幕的场景）。

const EGLint surfaceAttribs[] = {
    EGL_WIDTH, width,
    EGL_HEIGHT, height,
    EGL_NONE};   

m_eglOffScreenSurface = eglCreatePbufferSurface(m_eglDisplay, m_eglConfig, surfaceAttribs);

6） 绑定OpenGL所在的线程（eglMakeCurrent）， 将渲染上下文（EGLContext）、渲染表面（EGLSurface）与当前线程关联，从而建立完整的 OpenGL ES 渲染环境。

eglMakeCurrent(m_eglDisplay, m_eglOffScreenSurface, m_eglOffScreenSurface, m_eglContext)

7） 创建定时器，1000/FPS 秒绘制一次 //实际上为native侧实现，这里使用ts便于理解 setInterval(() => { //添加OpenGL线程绘制任务 }, 1000/mFps);

3. OpenGL (画笔)

OpenGL的全称是 ​Open Graphics Library​（开放式图形库），它是一种跨语言、跨平台的应用程序编程接口（API），专门用于渲染2D和3D矢量图形。

1） 生成纹理ID

glGenTextures(1, &m_texture);

2） 设置textureTarget纹理目标

// 定义纹理目标类型为GL_TEXTURE_EXTERNAL_OES（用于外部图像流，如相机/视频）
uint32_t target = GL_TEXTURE_EXTERNAL_OES;

// 设置纹理缩小过滤方式为线性过滤（当纹理被缩小时使用）
// GL_LINEAR会基于周围纹素插值计算颜色，使缩小后的纹理更平滑
glTexParameterf(target, GL_TEXTURE_MIN_FILTER, GL_LINEAR);  

// 设置纹理放大过滤方式为线性过滤（当纹理被放大时使用）
// GL_LINEAR通过加权平均周围4个纹素，减少放大时的锯齿感
glTexParameterf(target, GL_TEXTURE_MAG_FILTER, GL_LINEAR);  

// 设置纹理S轴（水平方向）的环绕方式为边缘截取
// GL_CLAMP_TO_EDGE表示超出[0,1]范围的坐标会使用边缘像素填充
glTexParameteri(target, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);  

// 设置纹理T轴（垂直方向）的环绕方式为边缘截取
// 避免纹理在边缘处重复或镜像，适用于需要严格对齐的场景（如视频帧）
glTexParameteri(target, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);

3） 创建​nativeImage​，并将纹理目标绑定到纹理ID

//HarmonyOS提供的接口内部已经实现绑定操作
m_nativeImage = OH_NativeImage_Create(m_texture, target);

//若为Android等平台需要显示的绑定纹理目标到纹理ID
glBindTexture(target, m_texture)

4） 设置帧可用回调

OH_OnFrameAvailableListener listener;
listener.context = this;
listener.onFrameAvailable = pri_OH_OnFrameAvailable;
OH_NativeImage_SetOnFrameAvailableListener(m_nativeImage, listener);
//有可用帧，可以开始draw到surface了。
void static pri_OH_OnFrameAvailable(void *context)
{
    OGRenderWindowBridge*the = (OGRenderWindowBridge*)context;
    the->m_bRead = true;
}

5） 创建nativeWindow，并获取对应的surfaceId，用于接收相机传输的数据

m_nativeWindow = OH_NativeImage_AcquireNativeWindow(m_nativeImage);
OH_NativeImage_GetSurfaceId(m_nativeImage, &o_surfaceId);

4. 启用XComponent

1） 创建自定义XComponentController

//新建XComponentController
class MyXComponentController extends XComponentController{
  public myXComponentInfo: MyXComponentInfo;

  public constructor(myXComponentInfo: MyXComponentInfo) {
    super();
    this.myXComponentInfo = myXComponentInfo;
  }

  onSurfaceCreated(surfaceId: string): void {
      //native侧初始化，包括EGL，OpenGL，以及myXComponentInfo参数传递到native侧

      //将该XComponent对应的surfaceId通过napi传递给native侧，创建对应的nativeWindow作为XComponent的生产者。
      setWindow(surfaceId, rect.surfaceWidth, rect.surfaceHeight, 1)

      //将OpenGL对应的surfaceId绑定给相机，相机作为生产者
  }

  onSurfaceChanged(surfaceId: string, rect: SurfaceRect): void {
      //通过napi调用native侧代码，重新setWindow
      setWindow(surfaceId, rect.surfaceWidth, rect.surfaceHeight, 1)
  }

  onSurfaceDestroyed(surfaceId: string): void {

  }
}

2） 创建XComponent

build() {
  XComponent({
    id: 'MyXComponent',
    type: XComponentType.SURFACE,
    controller: this.myXComponentController
  })
    .position({ x: this.myXComponentInfo.x, y: this.myXComponentInfo.y })
    .width(this.myXComponentInfo.w)
    .height(this.myXComponentInfo.h)
}

3） native侧核心设置代码，ts侧需要通过napi调用。

int setWindow(int64_t surfaceId, int i_width, int i_height, int i_state)
{
    //native侧处理XComponent对应的surfaceId
    OHNativeWindow* XComponentWindow;
    OH_NativeWindow_CreateNativeWindowFromSurfaceId(surfaceId, &XComponentWindow);
    eglSurface = eglCreateWindowSurface(XComponentWindow, m_eglConfig, m_eglWindow, NULL);
    //这里宽高代表分辨率，如i_width = 720,i_height = 1280 代表需要绘制的分辨率为720p。
    //添加到渲染队列中
    m_eglSurfaceQueue.push_back(eglSurface, i_width, i_height, i_state);
}

5. 相关参考文档

• NativeImage开发指导 (C/C++)
• NativeWindow开发指导 (C/C++)
• OpenGL ES
• Node-API
• 自定义渲染 (XComponent)