Surface 类型

本页面介绍了在 Media3 中可用于视频播放的不同类型的 Surface，以及如何根据您的应用场景选择合适的类型。如需详细了解 Android 中的 Surface 对象，请参阅此图形文档。

设置购买途径

Player 有四个入口点，可用于将其视频输出连接到某个 Surface：

• void setVideoSurface(@Nullable Surface surface)
• void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void setVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void setVideoTextureView(@Nullable TextureView textureView)

您还可以通过其他方式清除此错误：

• void clearVideoSurface()
• void clearVideoSurface(@Nullable Surface surface)
• void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void clearVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void clearVideoTextureView(@Nullable TextureView textureView)

为 PlayerView 选择一种 Surface 类型

PlayerView 的 surface_type 属性可用于设置视频播放所用的 Surface 类型。允许的值包括：

• surface_view (SurfaceView)
• texture_view (TextureView)
• spherical_gl_surface_view (SphericalGLSurfaceView) - 用于球形视频播放
• video_decoder_gl_surface_view (VideoDecoderGLSurfaceView) - 使用扩展渲染器的视频渲染
• none - 仅用于音频播放，应使用此属性来避免创建 Surface，因为创建 Surface 会产生较高的开销。

如果视图用于常规视频播放，则应使用 surface_view 或 texture_view。与 TextureView 相比，SurfaceView 在视频播放方面具有多项优势：

• 在许多设备上显著降低能耗。
• 帧计时更准确，从而使视频播放更流畅。
• 在支持的设备上支持更高质量的 HDR 视频输出。
• 支持在播放受 DRM 保护的内容时进行安全输出。
• 在对界面层进行放大处理的 Android TV 设备上，能够以显示屏的完整分辨率渲染视频内容。

因此，应尽可能优先使用 SurfaceView 而不是 TextureView。只有在 SurfaceView 无法满足您的需求时，才应使用 TextureView。例如，在 Android 7.0（API 级别 24）之前，需要对视频 Surface 进行平滑动画处理或滚动，请参阅以下说明。在这种情况下，最好仅当 SDK_INT 小于 24（Android 7.0）时使用 TextureView，否则使用 SurfaceView。

注意：在 Android 7.0（API 级别 24）之前，SurfaceView 渲染未与视图动画正确同步。在早期的版本中，当 SurfaceView 位于滚动容器中或进行动画处理时，同步不当可能会导致异常效果。可能出现的异常效果包括视图内容显示略有延迟，或在动画过程中画面变黑。为了在 Android 7.0 之前实现视频的流畅动画或滚动效果，请使用 TextureView 而不是 SurfaceView。

注意：SurfaceView 的 Surface 生命周期与视图可见性相关联，而 TextureView 的 Surface 生命周期与窗口附加和分离相关联。因此，在采用 SurfaceView 的滚动界面中，开始播放可能需要更长时间，因为输出 Surface 要稍晚才会可用。从 Android 14 开始，PlayerView 使用 SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) 来避免此行为。如果您的应用直接使用 SurfaceView（不使用 PlayerView），则可能需要启用此模式。在 Android 14 之前，可以通过在回收视图时将其平移到屏幕外来解决 Surface 被销毁的问题。

注意：部分 Android TV 设备以低于显示屏完整分辨率的分辨率运行其界面层，并将其放大后呈现给用户。例如，在具有 4K 显示屏的 Android TV 上，界面层可能以 1080p 分辨率运行。在这些设备上，必须使用 SurfaceView 以显示屏的完整分辨率渲染内容。可以使用 Util.getCurrentDisplayModeSize 查询显示屏的完整分辨率（以当前显示模式为准）。可以使用 Android 的 Display.getSize API 查询界面层分辨率。

注意：如果您在 AndroidView 内使用 PlayerView，我们无法保证兼容性，因为 PlayerView 在设计时并未考虑 Compose。SDK_INT == 34 的常见问题之一是 Surface 出现拉伸、裁剪或错位，导致与父容器 (AspectRatioFrameLayout) 不匹配。您可以通过调用 PlayerView.setEnableComposeSurfaceSyncWorkaround 选择启用 Compose 解决方法，但请注意，这会导致基于 XML 的共享过渡出现问题。

在 Compose 中选择 Surface 类型

在 Compose 中，互操作解决方案使用 AndroidView 可组合项来封装 SurfaceView 和 TextureView。与此对应的两个可组合项是 androidx.compose.foundation 中的 AndroidExternalSurface 和 AndroidEmbeddedExternalSurface。不过，这些代理类提供的 API 表面会限制对底层视图的访问。Player 需要这些视图来处理界面的完整生命周期（创建和大小更新）。

在 media3-ui-compose 模块中，您可以找到 ContentFrame 和 PlayerSurface 可组合项，它们以生命周期感知的方式将 Player 关联到 Surface。在这种情况下，表面类型为：

• androidx.media3.ui.compose.SURFACE_TYPE_SURFACE_VIEW
• androidx.media3.ui.compose.SURFACE_TYPE_TEXTURE_VIEW

没有 none 类型，因为这相当于未在 Compose 界面树中包含可组合项。