# XComponent图形渲染常见问题定位指导

## 概述

[XComponent](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent)组件作为一种渲染组件，可用于满足开发者实现高级自定义渲染的需求，例如相机预览流的显示和游戏画面的渲染。XComponent渲染时可能出现黑屏、卡顿等问题，本文从[XComponent渲染原理](#section626613618205)、[图形渲染定位工具链](#section074510384219)、[典型案例分析思路](#section1140135819212)三个方面提供定位排查指导。

## XComponent渲染原理

XComponent组件负责创建Surface，并通过回调将Surface的相关信息告知应用。应用可以通过一系列接口设定Surface的属性。该组件本身不对所绘制的内容进行感知，亦不提供渲染绘制的接口。XComponent渲染的架构图如下图所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3f/v3/dJo1eWEnRAmBmTN5H9Ijog/zh-cn_image_0000002717582231.jpg?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=DFD0444D19E5AC38BDF96885C47A430C22406D941D8FA6B027B2BEE52F20C18D "点击放大")

XComponent持有一个Surface，开发者能通过调用[NativeWindow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-nativewindow)模块的接口，申请并提交Buffer至图形队列，以此方式将自绘制内容传送至该Surface，其主体流程如下图所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/70/v3/N0NoV6HHT-KHFKA6qc3sFQ/zh-cn_image_0000002687982486.jpg?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=1951CA18F8D40155B775AE7E5CDF872D599896367B50E39485F6FC3D3876999D "点击放大")

数据流向图如下图所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8c/v3/9PXjt4lpS061wk8P3g1AjA/zh-cn_image_0000002717742103.jpg?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=D0C9CDF68D8068A0E72DB55148803802302745CD15E71197DC84A011DE0E9148 "点击放大")

经过上述流程，应用自绘制的内容就可以显示在XComponent持有的Surface区域，而XComponent则负责将此Surface整合进UI界面，其中展示的内容正是开发者发送的自绘制内容。Surface的默认位置与大小与XComponent组件一致，开发者可利用[setXComponentSurfaceRect()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent#setxcomponentsurfacerect12)接口自定义调整Surface的位置和大小。

## 图形渲染定位工具链

### HiLog关键日志信息及常见错误码

* XComponent组件关键日志信息 在日志里面搜索XComponent，可以获取组件id信息、[onSurfaceCreated()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent#onsurfacecreated12)和[onLoad()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent#onload)的触发信息、通过[getXComponentSurfaceId()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent#getxcomponentsurfaceid9)获取的Surface id信息，如下图所示：

  ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/4f/v3/y54mgfutREKHZO96clFycA/zh-cn_image_0000002687822624.png?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=93E637CA8875355D5F4CE97D12A2D27D36C991304838949A037B02378F4D7BDF "点击放大")


* 图形渲染异常信息及错误码 在日志中搜索C01401或Bufferqueue，可以获取图形渲染异常信息和对应的错误码。错误码可参考[OHNativeErrorCode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-graphic-error-code-h#ohnativeerrorcode)，异常信息如下图所示：

  ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/31/v3/cCRJ7u05RPC3pPq8X-DvgA/zh-cn_image_0000002717582233.png?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=CB5FD47A18BB6CDDFA82DD64E0CA9B7FC972D2B5890B0C953CA9CC09251769F5 "点击放大")

### Hidumper查询图形渲染信息

* 查询UI组件树 参考[获取期望应用组件树](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hidumper#获取期望应用组件树)获取组件树信息，然后搜索XComponent，可获取XComponent组件信息，如下图所示：

  ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e4/v3/do3o4zMiRAupGanbDDj9-A/zh-cn_image_0000002687982488.png?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=55D4538BE126A7925C67B79E14300E191D300BBDBBBE7D38B0DA516087D6029C "点击放大")

* 查询Render Service服务能力 参考[获取系统服务详细信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hidumper#获取系统服务详细信息)获取Render Service信息，如下图所示：

  ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/49/v3/QxtW_wdhThKdMIGl8RSq4Q/zh-cn_image_0000002717742105.jpg?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=6D16AA886EB2A0BF082D061DAA1BC04B416F5AE66FC7C5BE027039D91504A5DB "点击放大")


* 查询Render Service常见信息 使用hdc shell "hidumper -s RenderService -a allInfo"命令可同时获取surface、RS树等信息。

  1. 获取RS树信息

  RS树是Render Service根据UI组件树转换成的渲染树信息。使用hdc shell "hidumper -s RenderService -a RSTree" > RSTree.dump命令获取RS树信息，然后搜索SURFACE_NODE，可获取XComponent组件对应的节点信息，如下图所示：

  ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/79/v3/FQsaMLATTqq-z9ej2Rgi8g/zh-cn_image_0000002687822626.jpg?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=708263A76CB96664604AD5B74EA9E483A53DF8FEF1F8111E00147E2D63E2693F "点击放大")

  2. 获取surface信息

  使用hdc shell "hidumper -s RenderService -a surface" > surface.dump命令获取surface信息，然后根据XComponent id或者XComponent的Surface id搜索，可获取XComponent组件对应的surface信息和图形队列信息，如下图所示：

  ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/93/v3/FBtSzTEzQ0-O5NojnnDSlQ/zh-cn_image_0000002717582235.jpg?HW-CC-KV=V1&HW-CC-Date=20261014T084635Z&HW-CC-Expire=31536000000&HW-CC-Sign=C9AAA8144202196FF59C6E5ED62FB81975CC42EA172D35C127603031A99BF45D "点击放大")

### Frame分析图形渲染帧异常信息

* 查看Frame数据信息 参考[查看指定时间段内所有进程的Frame数据统计信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-insight-session-frame#section670916141348)。


* 分析Frame数据信息 参考[分析Frame数据](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-frame-case#section116411449153910)。

## 典型案例分析思路

### XComponent生命周期异常问题分析思路

**问题描述**

使用[OH_NativeXComponent](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-oh-nativexcomponent-native-xcomponent-oh-nativexcomponent)的[OnSurfaceCreated()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-oh-nativexcomponent-native-xcomponent-oh-nativexcomponent-callback#onsurfacecreated)接口从XComponent组件获取NativeWindow后，传递给渲染子线程使用，当页面退出，XComponent组件销毁时，出现崩溃。

**可能根因**

1. XComponent组件销毁时会将NativeWindow引用计数减一，若减为0析构后，子线程仍在使用会导致崩溃。
2. OH_NativeXComponent实例生命周期与XComponent组件强相关，如果在XComponent组件销毁后仍然操作该对象，将可能出现稳定性问题，造成应用的崩溃。

**解决方案**

1. 在将NativeWindow传递给子线程前，使用[OH_NativeWindow_NativeObjectReference()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativeobjectreference)将其引用计数加一；当子线程使用完成后，使用[OH_NativeWindow_NativeObjectUnreference()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativeobjectunreference)将其引用计数减一。
2. 参考[OH_NativeXComponent向OH_ArkUI_SurfaceHolder的迁移](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/napi-xcomponent-guidelines#oh_nativexcomponent向oh_arkui_surfaceholder的迁移)，使用[OH_ArkUI_SurfaceHolder](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-oh-nativexcomponent-native-xcomponent-oh-arkui-surfaceholder)相关接口代替OH_NativeXComponent相关接口。

### XComponent与其它组件图层叠加异常问题分析思路

**问题描述**

使用XComponent组件绘制内容的背景是透明的，但是层叠布局只能看到第一层绘制的内容。

**可能根因**

当开发者传输的绘制内容包含透明元素时，Surface区域的显示效果会与下方内容进行合成展示。如果传输内容完全透明，将XComponent的背景色设置成黑色，最终显示为一片黑色区域，层叠布局下方的内容将不可见。

**解决方案**

将XComponent组件的backgroundColor设置为透明。

### 画面黑屏问题分析思路

**问题描述**

使用XComponent组件渲染，画面黑屏。

**可能根因**

1. XComponent生命周期异常，例如组件没有创建、Surface id异常。
2. XComponent渲染异常，例如RS树上没有XComponent节点、XComponent的宽或高为0。
3. 应用发送的Buffer数据异常，例如未发送Buffer、发送了全黑的Buffer。

**解决方案**

1. 参考[XComponent组件关键日志信息](#li1487614291715)，排查[onSurfaceCreated()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent#onsurfacecreated12)/[onLoad()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-xcomponent#onload)是否触发成功、Surface id是否正常。参考[创建XComponent和管理Surface生命周期](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/napi-xcomponent-guidelines#创建xcomponent和管理surface生命周期)，选择合适的方式创建XComponent并管理XComponent持有Surface的生命周期。
2. 参考[Hidumper查询图形渲染信息](#section18599934133515)，排查UI树和RS树是否存在XComponent节点，节点的宽高是否正常，visibility等属性是否正常。
3. 排查上层链路的功能是否正常，例如相机预览、解码器出帧、OpenGL处理等是否正常。

### 画面闪烁问题分析思路

**问题描述**

页面切换时，XComponent渲染画面出现闪烁。

**可能根因**

XComponent组件销毁重建或XComponent属性发生变化。

**解决方案**

参考[Hidumper查询图形渲染信息](#section18599934133515)，排查UI树和RS树上的XComponent节点信息是否有变化，例如id、宽高、背景色、透明度等属性是否有变化。

### 画面撕裂问题分析思路

**问题描述**

从XComponent对应的NativeWindow中获取Buffer并进行绘制，送显后画面出现花屏、裂屏。

**可能根因**

使用[OH_NativeWindow_NativeWindowRequestBuffer()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativewindowrequestbuffer)获取Buffer时，会返回一个fenceFd，这个fenceFd是消费者进程创建的一个文件句柄，表示消费者是否已完成Buffer消费。只有消费端完成消费后，生产者才可以开始填充Buffer，否则会造成花屏、裂屏等问题。

**解决方案**

调用[OH_NativeWindow_NativeWindowRequestBuffer()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativewindowrequestbuffer)后，等待fenceFd等于-1（-1表示消费者已完成Buffer消费）后，再将生产的内容写入Buffer。详细使用方法可参考[NativeWindow开发指导 (C/C++)](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/native-window-guidelines)。

### 画面卡顿问题分析思路

**问题描述**

从XComponent对应的NativeWindow中获取Buffer并进行绘制，连续渲染时画面出现卡顿。

**可能根因**

1. 生产端填充Buffer的时间过长，即生产端速度<消费端速度，导致卡顿。
2. 为了确保不同来源的复杂绘制效果能在同一时间节点完成绘制、合成与显示，Render Service依赖VSync实现全局统一的信号收发机制。如果在使用[OH_NativeWindow_NativeWindowFlushBuffer()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativewindowflushbuffer)提交Buffer时，没有申请[NativeVsync](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-nativevsync)，会导致应用的绘制帧率与系统帧率不同步，出现卡顿。

**解决方案**

1. 提高生产端的生产速度，例如使用硬件解码、优化后处理算法等。
2. 参考[NativeVSync开发指导 (C/C++)](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/native-vsync-guidelines)，在提交Buffer时，申请VSync。

### 渲染内存泄漏问题分析思路

**问题描述**

使用[OH_NativeImage_AcquireNativeWindowBuffer()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-image-h#oh_nativeimage_acquirenativewindowbuffer)获取Buffer，消费后已使用[OH_NativeImage_ReleaseNativeWindowBuffer()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-image-h#oh_nativeimage_releasenativewindowbuffer)归还Buffer，仍然出现内存泄漏。

**可能根因**

1. [OH_NativeImage_ReleaseNativeWindowBuffer()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-image-h#oh_nativeimage_releasenativewindowbuffer)只在成功时减少引用计数，未对返回值做处理会导致内存泄漏。
2. 使用[OH_NativeWindow_NativeObjectReference()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativeobjectreference)对Buffer增加一次引用计数后，未配套减少引用计数，导致该Buffer无法释放。

**解决方案**

1. [OH_NativeImage_ReleaseNativeWindowBuffer()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-image-h#oh_nativeimage_releasenativewindowbuffer)返回不为NATIVE_ERROR_OK时，额外调用[OH_NativeWindow_NativeObjectUnreference()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativeobjectunreference)减少一次引用计数。
2. 确保所有分支返回时都有配套调用[OH_NativeWindow_NativeObjectUnreference()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-external-window-h#oh_nativewindow_nativeobjectunreference)减少一次引用计数。