渲染诊断

本文用于排查黑屏、停帧、画面未提交和视频显示问题。探针默认关闭，打开后只用于定位问题。

开启探针

CI 手动构建时启用 enable_render_probe=true，并按需要设置 log_level=debug 或 trace。本地构建可设置：

cmake -DENABLE_RENDER_PROBE=ON <其他参数>
cmake -DKRKR_LOG_LEVEL=debug <其他参数>

排查结束后关闭探针，避免高频日志改变时序。

关键日志

前缀	作用
UpdateDrawBuffer	记录渲染路径、目标纹理、图层数和合成次数
SourceSample	采样引擎源纹理，判断引擎是否写入有效像素
IOSurfacePixelSample	判断共享 IOSurface 是否收到有效像素
BlackScreen	汇总连续黑屏时的绘制、图层和视频状态
engine_tick	记录桥接帧调用是否进入并返回
RequestUpdate	判断图层变化是否请求窗口重绘
DeliverWinUpdate	判断窗口重绘事件是否被投递和处理

判断顺序

1. 查看 SourceSample。源纹理非黑时，继续检查 blit 或共享纹理；源纹理全黑时，检查合成和图层更新。
2. 查看 draw 或合成次数。计数增长表示引擎仍在绘制；不增长时再检查更新请求、事件投递和绘制设备。
3. 查看 IOSurfacePixelSample 或 SurfaceTexture 路径，确认目标纹理收到像素。
4. 查看 engine_tick 的进入和返回记录，确认桥接调用没有停在中途。
5. 视频相关问题同时检查视频帧计数、播放状态和目标 Layer 更新，不能只根据黑屏判断视频故障。

avg=(0,0,0,255) 是不透明黑，通常表示源纹理没有被有效内容覆盖；avg=(0,0,0,0) 是透明黑，表示内容可能为空但透明度正常。

日志容量

日志使用旋转文件，单文件达到 4 MiB 后轮转，最多保留 3 份。默认日志级别按构建类型设置；只有定位问题时才提高级别。

报告要求

记录平台、构建类型、复现步骤、现象、关键日志前缀和期望行为。不要把个人路径、设备隐私、完整游戏资源或无关的高频日志提交到仓库。