Surface 边界问题总览

在 Android 多媒体渲染管线中，Surface 的边界定义直接决定最终画面的呈现效果。不同设备、不同系统版本、不同窗口模式下，Surface 的可见区域与逻辑边界并不总是重合，从而引出 黑边、拉伸、裁剪、安全区域、Display Cutout、屏幕圆角、多窗口与分屏边界 七类典型问题。本章作为整本指南的索引，逐一梳理每种问题的表现形式、根本原因以及通用解决思路，后续章节会深入每类问题的具体适配方案。

2.1 七类边界问题详解

1. 黑边 (Letterbox / Pillarbox)

   现象：画面四周出现黑色填充条，通常出现在 宽高比不匹配 或 Surface 尺寸小于显示区域 时。渲染管线中，如果 BufferQueue 输出的帧尺寸与 SurfaceFlinger 期望的尺寸不一致，SurfaceFlinger 会在合成阶段自动填入黑色像素。

   • 常见原因：视频源比例与屏幕比例不同且在 SurfaceView 中未正确设置 setAspectRatio；TextureView 的 SurfaceTexture 回调尺寸未与 View 尺寸同步。
   • 解决方向：在 Surface 创建时匹配期望尺寸，或使用 MediaCodec 的 onOutputSizeChanged 回调动态调整 View 大小。
2. 拉伸 (Stretch / Distortion)

   现象：画面被非均匀缩放，导致物体变形。本质是 Surface 的宽高比与渲染内容的像素比不一致。在 OpenGL ES 或 Vulkan 渲染中，视口 (viewport) 设置错误 是最常见的诱因。

   • 常见原因：glViewport() 参数错误；TextureView 的变换矩阵未正确处理宽高比；Surface 的 Canvas 裁剪未考虑缩放。
   • 解决方向：确保视口宽高比与渲染目标的宽高比一致，使用 Matrix.ScaleToFit 或自定义投影矩阵。
3. 裁剪 (Clipping / Truncation)

   现象：画面内容被切除一部分（如底部或顶部缺失）。原因包括 Surface 的矩形范围超出实际显示边界（例如在 SurfaceControl.Transaction 中设置了过大的裁剪矩形），或 BufferQueue 的帧尺寸大于 Surface 的尺寸，导致 SurfaceFlinger 自动裁剪多出的像素。

   • 常见错误：WindowManager.LayoutParams.softInputMode 与 SurfaceView 的裁剪区域冲突；在 onSurfaceChanged 回调中未更新裁剪矩形。
   • 解决方向：使用 SurfaceControl.Builder.setBufferSize() 精确控制帧尺寸，避免大于 View 实际大小。
4. 安全区域 (Safe Area / System Window Insets)

   现象：内容被系统栏（状态栏、导航栏）或凹口遮挡，用户无法点击或看到关键信息。安全区域是系统为 不可或缺的 UI 控件 预留的不可用区域，其尺寸由 WindowInsets 提供。

   • 适配关键：使用 ViewCompat.setOnApplyWindowInsetsListener() 或 WindowInsetsCompat 获取安全区域边界，然后调整 Surface 的布局 padding 或 margin。
   • 调试工具：adb shell dumpsys window visible 查看当前窗口 insets 值。
5. Display Cutout（刘海/打孔屏）

   现象：画面内容被屏幕挖孔区域遮挡，且系统默认会以 安全区域 的方式避开切口。Display Cutout 本质是 屏幕物理开口，其位置与形状由 OEM 厂商定义，通过 WindowInsets.getDisplayCutout() 获取。

   • 模式选择：在 WindowManager.LayoutParams 中设置 layoutInDisplayCutoutMode：MODE_ALWAYS（允许内容铺满，但需要自行规避切口区域）、MODE_SHORT_EDGES（默认，仅短边伸入切口）、MODE_NEVER（强制回退安全区域）。
   • 性能注意：MODE_ALWAYS 会增加 SurfaceFlinger 的合成复杂度，需在 高刷新率 场景下评估。
6. 屏幕圆角 (Screen Corner Radius / Rounded Corners)

   现象：画面内容溢出到被物理圆角裁剪的区域，导致角落内容显示异常。圆角区域由 WindowInsets.getRoundedCorner() 描述（API 31+）。

   • 适配思路：在 Surface 上绘制时手动添加 圆角裁剪路径（如 Path.addRoundRect()），或利用 ViewOutlineProvider 让系统自动裁剪。
   • 常见陷阱：非全屏窗口（如分屏模式）下圆角可能不存在或尺寸不同，需动态判断 getRoundedCorner() 是否非空。
7. 多窗口与分屏边界 (Multi-Window & Split-Screen Bounds)

   现象：进入多窗口模式后，Surface 的尺寸被系统强制缩放或重新创建，导致画面黑边、拉伸或裁剪。此时 Surface 的矩形不再是全屏，而是每个窗口的可用区域。

   • 关键机制：onConfigurationChanged() 会被触发，Activity 的 getWindow() 下的 Surface 尺寸由 WindowManager.getCurrentWindowMetrics() 决定。
   • 适配要点：监听 Configuration 中的 screenWidthDp/screenHeightDp 变化，并在 Surface 重建时重新设置 视口 和 BufferQueue 尺寸。

2.2 问题对比速查表

2.3 调试与验证基础命令

在工作中，以下命令组合可快速定位边界问题属于哪一类：

# 查看当前窗口的 insets 和 cutout 信息
adb shell dumpsys window visible

# 查看 SurfaceFlinger 合成的帧尺寸与黑边情况
adb shell dumpsys SurfaceFlinger

# 获取设备圆角信息（API 31+ 可用）
adb shell dumpsys window displays

# 模拟不同 cutout 模式进行测试（需 root 或模拟器）
adb shell settings put global force_display_cutout 1

# 查看窗口尺寸变化日志
adb logcat -s "WindowManager" "SurfaceView" "SurfaceControl"

2.4 性能与稳定性注意事项

• 多问题同时存在时的优先级： 先修复安全区域和 Display Cutout（用户可见遮挡），再处理黑边/拉伸（视觉质量），最后优化圆角与分屏边界（边缘体验）。
• Surface 重建成本： 每次边界问题修复都可能触发 Surface 重新创建（例如修改 layoutInDisplayCutoutMode），高帧率应用应避免频繁操作，尽量在 onSurfaceChanged 回调中统一做一次适配。
• 剪裁与合成性能： 对 Display Cutout 和圆角手动裁剪时，注意 GPU 片段着色器中的 discard 操作可能会降低渲染效率，可考虑预裁剪纹理或使用 Stencil 测试替代。

2.5 边界问题分类图

下图将七类问题按 “Surface 尺寸不匹配” 和 “系统 UI 覆盖” 两个维度组织，帮助理解它们之间的层次关系：

2.6 编程接口快速参考

以下代码段展示了获取安全区域与 Display Cutout 信息的基本方式，是后续章节频繁调用的基础 API：

// 在 Fragment 或 Activity 的 onViewCreated 中
ViewCompat.setOnApplyWindowInsetsListener(view) { v, insets ->
    val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
    val cutout = insets.displayCutout

    // 安全区域边距
    val leftSafe = systemBars.left
    val topSafe = systemBars.top
    val rightSafe = systemBars.right
    val bottomSafe = systemBars.bottom

    // Display Cutout 切口位置（可能为 null）
    cutout?.let {
        val cutoutLeft = it.safeInsetLeft
        val cutoutTop = it.safeInsetTop
        // ...
    }

    // 圆角（API 31+）
    val roundedCorner = insets.getRoundedCorner(RoundedCornerPosition.TOP_LEFT)
    roundedCorner?.let {
        val radius = it.radius
        val centerX = it.center.x
        val centerY = it.center.y
    }

    // 返回消耗 insets（不要消费否则会影响子 View）
    insets
}