HarmonyOS NativeWindow 渲染闭环Buffer申请、Fence同步与异常归还NativeWindow渲染最危险的问题通常不是“画面没画出来”而是申请到Buffer后某条异常路径没有归还。前几帧可能正常运行一段时间后RequestBuffer开始阻塞表面上像GPU卡死实际是生产者耗尽了Buffer队列。Fence处理错误也会造成撕裂、读写竞争或文件描述符泄漏。本文以XComponent提供的窗口为入口完整走通窗口配置、Buffer申请、release fence等待、CPU写入、Flush提交与Abort归还。重点不是画一个颜色块而是建立“每次申请必有结局”的资源协议。1. 先认识生产者与消费者NativeWindow位于图形生产者一侧。应用从队列申请一块可写Buffer完成渲染后提交显示系统作为消费者取走Buffer并合成。消费者使用结束后通过fence告诉生产者何时可以再次写入。应用生产者 - RequestBuffer - 等待可写 - 写入内容 应用生产者 - FlushBuffer - Buffer队列 - 显示消费者 应用失败 - AbortBuffer - Buffer重新回到队列因此RequestBuffer成功之后只能有两个合法结果成功内容走FlushBuffer失败内容走AbortBuffer。直接return不是第三种结果。2. 工程先链接正确的系统库NativeWindow接口由系统NDK提供。CMake目标通常需要链接libace_ndk.z.so和libnative_window.so并包含XComponent与NativeWindow头文件。target_link_libraries(entry PUBLIC libace_napi.z.so libace_ndk.z.so libnative_window.so libhilog_ndk.z.so )#includeace/xcomponent/native_interface_xcomponent.h#includenative_window/external_window.h#includenative_window/buffer_handle.h#includepoll.h#includeunistd.h库名与头文件以当前SDK为准。若项目只做EGL或Vulkan渲染还要链接对应图形库但Buffer归还原则不变。3. NativeWindow生命周期跟随SurfaceXComponent的Surface创建回调提供NativeWindowSurface销毁后旧指针不再可用。跨线程保存时要明确所有权并在持有期间增加引用计数。structRenderContext{OHNativeWindow*windownullptr;int32_twidth0;int32_theight0;boolsurfaceReadyfalse;};voidBindWindow(RenderContextctx,OHNativeWindow*window,int32_twidth,int32_theight){if(ctx.window!nullptr){OH_NativeWindow_NativeObjectUnreference(ctx.window);}ctx.windowwindow;ctx.widthwidth;ctx.heightheight;ctx.surfaceReadywindow!nullptr;if(ctx.window!nullptr){OH_NativeWindow_NativeObjectReference(ctx.window);}}Surface销毁回调应停止渲染线程、等待正在执行的帧退出再释放窗口引用。先释放窗口、后停止线程会产生悬空访问。4. 原生缓冲链路包含一条异常返回路绑定窗口后先配置几何与格式再申请Buffer。申请返回的fence表示消费者何时释放了该Buffer等待完成后才能写。写入成功提交写入失败归还。异常返回路必须和正常提交路同等明确。5. 申请前设置几何、格式和用途至少设置宽高与像素格式。配置应在尺寸变化时更新不要在每帧重复执行。boolConfigureWindow(OHNativeWindow*window,int32_twidth,int32_theight){if(windownullptr||width0||height0){returnfalse;}if(OH_NativeWindow_NativeWindowHandleOpt(window,SET_BUFFER_GEOMETRY,width,height)!0){returnfalse;}if(OH_NativeWindow_NativeWindowHandleOpt(window,SET_FORMAT,GRAPHIC_PIXEL_FMT_RGBA_8888)!0){returnfalse;}returntrue;}若Buffer由CPU写入需要保留CPU访问能力纯GPU渲染可按官方建议关闭不需要的CPU访问以降低开销。用途与实际访问方式必须一致。6. Request返回的Fence先等待再关闭OH_NativeWindow_NativeWindowRequestBuffer返回OHNativeWindowBuffer*和一个fence fd。该fd用于等待上一位消费者释放Buffer。应用用完这个fd后负责关闭。boolWaitReleaseFence(intfenceFd,inttimeoutMs){if(fenceFd0){returntrue;}pollfd item{fenceFd,POLLIN,0};intresultpoll(item,1,timeoutMs);close(fenceFd);returnresult0;}超时不能继续写入同一Buffer。此时应走Abort路径并记录帧号、等待时长与窗口代次不能无限阻塞UI线程。7. 每次申请都交给守卫对象收口C的RAII可以把默认结局设为Abort只有Flush成功才标记完成。这样新增任何return或异常分支都不会漏还Buffer。classRequestedBufferGuard{public:RequestedBufferGuard(OHNativeWindow*window,OHNativeWindowBuffer*buffer):window_(window),buffer_(buffer){}~RequestedBufferGuard(){if(!finished_window_!nullptrbuffer_!nullptr){OH_NativeWindow_NativeWindowAbortBuffer(window_,buffer_);}}voidMarkFinished(){finished_true;}private:OHNativeWindow*window_nullptr;OHNativeWindowBuffer*buffer_nullptr;boolfinished_false;};守卫不替代错误处理它只保证队列协议。Abort失败仍应记录并停止继续申请避免在失效窗口上形成循环。8. CPU写入示例要考虑strideBuffer每行实际字节数可能大于width * 4必须使用BufferHandle.stride。下面绘制纯色帧并让守卫覆盖所有失败出口。boolDrawSolidFrame(OHNativeWindow*window,int32_twidth,int32_theight,uint32_tcolor){OHNativeWindowBuffer*buffernullptr;intreleaseFenceFd-1;int32_trequestResultOH_NativeWindow_NativeWindowRequestBuffer(window,buffer,releaseFenceFd);if(requestResult!0||buffernullptr){returnfalse;}RequestedBufferGuardguard(window,buffer);if(!WaitReleaseFence(releaseFenceFd,1000)){returnfalse;}BufferHandle*handleOH_NativeWindow_GetBufferHandleFromNative(buffer);if(handlenullptr||handle-virAddrnullptr||handle-stride0){returnfalse;}auto*pixelsstatic_castuint8_t*(handle-virAddr);for(int32_ty0;yheight;y){auto*rowreinterpret_castuint32_t*(pixelsy*handle-stride);for(int32_tx0;xwidth;x){row[x]color;}}Rect rect{0,0,width,height};Region region{rect,1};int32_tflushResultOH_NativeWindow_NativeWindowFlushBuffer(window,buffer,-1,region);if(flushResult!0){returnfalse;}guard.MarkFinished();returntrue;}CPU同步写入完成后提交时传-1表示没有额外acquire fence。特别注意不能把Request返回的release fence原样传给Flush两者语义不同。9. Buffer队列边界不能跨错线程OH_NativeWindow_NativeWindowRequestBuffer、FlushBuffer与HandleOpt是非线程安全接口。最简单的策略是每个窗口只由一个渲染线程访问尺寸变化与销毁通过消息投递到该线程执行。enumclassRenderCommandType{RESIZE,DRAW,DESTROY};structRenderCommand{RenderCommandType type;int32_twidth;int32_theight;};不要让UI线程更新几何、渲染线程同时申请Buffer。即使偶尔成功也会产生难以复现的竞态。10. Flush失败后仍要尝试AbortFlush失败意味着Buffer未确认进入消费者队列。守卫会继续执行Abort如果窗口已失效Abort也可能失败此时应终止渲染循环并等待新的Surface回调。Request失败 - 本帧无Buffer不执行Abort Fence等待失败 - Abort已申请Buffer停止或跳过本帧 写入失败 - Abort已申请Buffer Flush成功 - 标记完成不再Abort Flush失败 - 尝试Abort并停止旧窗口渲染 Surface销毁 - 停线程、等帧退出、释放窗口引用11. 用计数器找出队列泄漏为每个窗口维护requestSuccess、flushSuccess、abortAttempt和inFlight。正常情况下帧结束后inFlight回到0且成功申请数应等于成功提交数与归还尝试数之和。structBufferStats{uint64_trequestSuccess0;uint64_tflushSuccess0;uint64_tabortAttempt0;int32_tinFlight0;};统计只记录数值与窗口代次不在每帧输出大量日志。出现阻塞时再打印最近一次错误、未归还数量和Surface状态。12. NativeWindow验收场景[ ] Request成功后的每条路径都Flush或Abort [ ] release fence等待后由应用关闭 [ ] Flush未复用Request返回的fence fd [ ] CPU写入使用Buffer真实stride [ ] 尺寸变化与Buffer操作位于同一渲染线程 [ ] Surface销毁前渲染线程已经停止 [ ] 连续运行和频繁前后台切换后inFlight仍为0 [ ] Flush故障注入后队列可以恢复或安全停止13. NativeWindow资料索引NativeWindow开发指导Native常见错误说明external_window.h与buffer_handle.h以本机HarmonyOS SDK API 23头文件为准。原生渲染稳定性的底线是守住Buffer所有权Request取得暂时所有权Fence确认可写Flush移交给消费者Abort归还失败帧。把这个协议写进守卫和计数器比在卡死后增加超时重试更可靠。
HarmonyOS NativeWindow 渲染闭环：Buffer申请、Fence同步与异常归还
HarmonyOS NativeWindow 渲染闭环Buffer申请、Fence同步与异常归还NativeWindow渲染最危险的问题通常不是“画面没画出来”而是申请到Buffer后某条异常路径没有归还。前几帧可能正常运行一段时间后RequestBuffer开始阻塞表面上像GPU卡死实际是生产者耗尽了Buffer队列。Fence处理错误也会造成撕裂、读写竞争或文件描述符泄漏。本文以XComponent提供的窗口为入口完整走通窗口配置、Buffer申请、release fence等待、CPU写入、Flush提交与Abort归还。重点不是画一个颜色块而是建立“每次申请必有结局”的资源协议。1. 先认识生产者与消费者NativeWindow位于图形生产者一侧。应用从队列申请一块可写Buffer完成渲染后提交显示系统作为消费者取走Buffer并合成。消费者使用结束后通过fence告诉生产者何时可以再次写入。应用生产者 - RequestBuffer - 等待可写 - 写入内容 应用生产者 - FlushBuffer - Buffer队列 - 显示消费者 应用失败 - AbortBuffer - Buffer重新回到队列因此RequestBuffer成功之后只能有两个合法结果成功内容走FlushBuffer失败内容走AbortBuffer。直接return不是第三种结果。2. 工程先链接正确的系统库NativeWindow接口由系统NDK提供。CMake目标通常需要链接libace_ndk.z.so和libnative_window.so并包含XComponent与NativeWindow头文件。target_link_libraries(entry PUBLIC libace_napi.z.so libace_ndk.z.so libnative_window.so libhilog_ndk.z.so )#includeace/xcomponent/native_interface_xcomponent.h#includenative_window/external_window.h#includenative_window/buffer_handle.h#includepoll.h#includeunistd.h库名与头文件以当前SDK为准。若项目只做EGL或Vulkan渲染还要链接对应图形库但Buffer归还原则不变。3. NativeWindow生命周期跟随SurfaceXComponent的Surface创建回调提供NativeWindowSurface销毁后旧指针不再可用。跨线程保存时要明确所有权并在持有期间增加引用计数。structRenderContext{OHNativeWindow*windownullptr;int32_twidth0;int32_theight0;boolsurfaceReadyfalse;};voidBindWindow(RenderContextctx,OHNativeWindow*window,int32_twidth,int32_theight){if(ctx.window!nullptr){OH_NativeWindow_NativeObjectUnreference(ctx.window);}ctx.windowwindow;ctx.widthwidth;ctx.heightheight;ctx.surfaceReadywindow!nullptr;if(ctx.window!nullptr){OH_NativeWindow_NativeObjectReference(ctx.window);}}Surface销毁回调应停止渲染线程、等待正在执行的帧退出再释放窗口引用。先释放窗口、后停止线程会产生悬空访问。4. 原生缓冲链路包含一条异常返回路绑定窗口后先配置几何与格式再申请Buffer。申请返回的fence表示消费者何时释放了该Buffer等待完成后才能写。写入成功提交写入失败归还。异常返回路必须和正常提交路同等明确。5. 申请前设置几何、格式和用途至少设置宽高与像素格式。配置应在尺寸变化时更新不要在每帧重复执行。boolConfigureWindow(OHNativeWindow*window,int32_twidth,int32_theight){if(windownullptr||width0||height0){returnfalse;}if(OH_NativeWindow_NativeWindowHandleOpt(window,SET_BUFFER_GEOMETRY,width,height)!0){returnfalse;}if(OH_NativeWindow_NativeWindowHandleOpt(window,SET_FORMAT,GRAPHIC_PIXEL_FMT_RGBA_8888)!0){returnfalse;}returntrue;}若Buffer由CPU写入需要保留CPU访问能力纯GPU渲染可按官方建议关闭不需要的CPU访问以降低开销。用途与实际访问方式必须一致。6. Request返回的Fence先等待再关闭OH_NativeWindow_NativeWindowRequestBuffer返回OHNativeWindowBuffer*和一个fence fd。该fd用于等待上一位消费者释放Buffer。应用用完这个fd后负责关闭。boolWaitReleaseFence(intfenceFd,inttimeoutMs){if(fenceFd0){returntrue;}pollfd item{fenceFd,POLLIN,0};intresultpoll(item,1,timeoutMs);close(fenceFd);returnresult0;}超时不能继续写入同一Buffer。此时应走Abort路径并记录帧号、等待时长与窗口代次不能无限阻塞UI线程。7. 每次申请都交给守卫对象收口C的RAII可以把默认结局设为Abort只有Flush成功才标记完成。这样新增任何return或异常分支都不会漏还Buffer。classRequestedBufferGuard{public:RequestedBufferGuard(OHNativeWindow*window,OHNativeWindowBuffer*buffer):window_(window),buffer_(buffer){}~RequestedBufferGuard(){if(!finished_window_!nullptrbuffer_!nullptr){OH_NativeWindow_NativeWindowAbortBuffer(window_,buffer_);}}voidMarkFinished(){finished_true;}private:OHNativeWindow*window_nullptr;OHNativeWindowBuffer*buffer_nullptr;boolfinished_false;};守卫不替代错误处理它只保证队列协议。Abort失败仍应记录并停止继续申请避免在失效窗口上形成循环。8. CPU写入示例要考虑strideBuffer每行实际字节数可能大于width * 4必须使用BufferHandle.stride。下面绘制纯色帧并让守卫覆盖所有失败出口。boolDrawSolidFrame(OHNativeWindow*window,int32_twidth,int32_theight,uint32_tcolor){OHNativeWindowBuffer*buffernullptr;intreleaseFenceFd-1;int32_trequestResultOH_NativeWindow_NativeWindowRequestBuffer(window,buffer,releaseFenceFd);if(requestResult!0||buffernullptr){returnfalse;}RequestedBufferGuardguard(window,buffer);if(!WaitReleaseFence(releaseFenceFd,1000)){returnfalse;}BufferHandle*handleOH_NativeWindow_GetBufferHandleFromNative(buffer);if(handlenullptr||handle-virAddrnullptr||handle-stride0){returnfalse;}auto*pixelsstatic_castuint8_t*(handle-virAddr);for(int32_ty0;yheight;y){auto*rowreinterpret_castuint32_t*(pixelsy*handle-stride);for(int32_tx0;xwidth;x){row[x]color;}}Rect rect{0,0,width,height};Region region{rect,1};int32_tflushResultOH_NativeWindow_NativeWindowFlushBuffer(window,buffer,-1,region);if(flushResult!0){returnfalse;}guard.MarkFinished();returntrue;}CPU同步写入完成后提交时传-1表示没有额外acquire fence。特别注意不能把Request返回的release fence原样传给Flush两者语义不同。9. Buffer队列边界不能跨错线程OH_NativeWindow_NativeWindowRequestBuffer、FlushBuffer与HandleOpt是非线程安全接口。最简单的策略是每个窗口只由一个渲染线程访问尺寸变化与销毁通过消息投递到该线程执行。enumclassRenderCommandType{RESIZE,DRAW,DESTROY};structRenderCommand{RenderCommandType type;int32_twidth;int32_theight;};不要让UI线程更新几何、渲染线程同时申请Buffer。即使偶尔成功也会产生难以复现的竞态。10. Flush失败后仍要尝试AbortFlush失败意味着Buffer未确认进入消费者队列。守卫会继续执行Abort如果窗口已失效Abort也可能失败此时应终止渲染循环并等待新的Surface回调。Request失败 - 本帧无Buffer不执行Abort Fence等待失败 - Abort已申请Buffer停止或跳过本帧 写入失败 - Abort已申请Buffer Flush成功 - 标记完成不再Abort Flush失败 - 尝试Abort并停止旧窗口渲染 Surface销毁 - 停线程、等帧退出、释放窗口引用11. 用计数器找出队列泄漏为每个窗口维护requestSuccess、flushSuccess、abortAttempt和inFlight。正常情况下帧结束后inFlight回到0且成功申请数应等于成功提交数与归还尝试数之和。structBufferStats{uint64_trequestSuccess0;uint64_tflushSuccess0;uint64_tabortAttempt0;int32_tinFlight0;};统计只记录数值与窗口代次不在每帧输出大量日志。出现阻塞时再打印最近一次错误、未归还数量和Surface状态。12. NativeWindow验收场景[ ] Request成功后的每条路径都Flush或Abort [ ] release fence等待后由应用关闭 [ ] Flush未复用Request返回的fence fd [ ] CPU写入使用Buffer真实stride [ ] 尺寸变化与Buffer操作位于同一渲染线程 [ ] Surface销毁前渲染线程已经停止 [ ] 连续运行和频繁前后台切换后inFlight仍为0 [ ] Flush故障注入后队列可以恢复或安全停止13. NativeWindow资料索引NativeWindow开发指导Native常见错误说明external_window.h与buffer_handle.h以本机HarmonyOS SDK API 23头文件为准。原生渲染稳定性的底线是守住Buffer所有权Request取得暂时所有权Fence确认可写Flush移交给消费者Abort归还失败帧。把这个协议写进守卫和计数器比在卡死后增加超时重试更可靠。
