图形

图形

  

API 参考文档
androidx.graphics

利用多个 Android 平台版本中的图形工具

下表列出了 androidx.graphics 组中的所有工件。

制品	稳定版	候选版	Beta 版	Alpha 版
图形核心	1.0.1	-	-	-
图形路径	1.0.1	-	-	-
图形形状	1.0.1	-	-	-

此库的最后更新时间：2024 年 9 月 4 日

声明依赖项

如需添加 Graphics 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    implementation "androidx.graphics:graphics-core:1.0.2"
    implementation "androidx.graphics:graphics-path:1.0.1"
    implementation "androidx.graphics:graphics-shapes:1.0.1"
}

Kotlin

dependencies {
    implementation("androidx.graphics:graphics-core:1.0.2")
    implementation("androidx.graphics:graphics-path:1.0.1")
    implementation("androidx.graphics:graphics-shapes:1.0.1")
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

此工件没有版本说明。

Graphics Shapes 版本 1.0

版本 1.0.0

2024 年 8 月 21 日

发布了 androidx.graphics:graphics-shapes:1.0.0、androidx.graphics:graphics-shapes-android:1.0.0 和 androidx.graphics:graphics-shapes-desktop:1.0.0。版本 1.0.0 中包含这些提交内容。

版本 1.0.0-rc01

2024 年 7 月 24 日

发布了 androidx.graphics:graphics-shapes:1.0.0-rc01、androidx.graphics:graphics-shapes-android:1.0.0-rc01 和 androidx.graphics:graphics-shapes-desktop:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

版本 1.0.0-beta01

2024 年 5 月 1 日

发布了 androidx.graphics:graphics-shapes:1.0.0-beta01、androidx.graphics:graphics-shapes-android:1.0.0-beta01 和 androidx.graphics:graphics-shapes-desktop:1.0.0-beta01。版本 1.0.0-beta01 包含这些提交内容。

API 变更

• 允许预旋转形状，以便从不同的点开始。此更改允许 pillStar 形状从边界上的非默认点开始其曲线。在为形状路径的描边添加动画效果时，可以通过从形状轮廓上的特定位置开始绘制，这会非常有用。 （Ifbb4d、b/324303807）
• 向 Morph 添加了 calculateBounds() 函数，以便在 RoundedPolygon 上并行执行相同的函数。（I8a3b6、b/325463575）

版本 1.0.0-alpha05

2024 年 2 月 7 日

发布了 androidx.graphics:graphics-shapes:1.0.0-alpha05、androidx.graphics:graphics-shapes-android:1.0.0-alpha05 和 androidx.graphics:graphics-shapes-desktop:1.0.0-alpha05。版本 1.0.0-alpha05 中包含这些提交内容。

新功能

• 该库现在提供了新的 pill() 和 pillStar() 函数，用于轻松创建这些圆角/加星标的形状。我们还提供了一些新的 API，可用于计算形状所需的精确边界（之前的边界只是根据底层贝塞尔曲线定位点和控制点得出的估算值），以及可能的最大边界，如果容器在该容器内旋转，这可能有助于确定容器的大小。（I71827）

API 变更

• 现在提供了用于检索精确边界和最大边界的更多选项。（I6d49f、b/317286450）

bug 修复

• 由于与零长度曲线相关的低级别渲染问题，在将这些形状绘制为描边路径时，偶尔会出现渲染伪影。该 bug 通过消除所有零长度的曲线（形状不需要，因此还节省了形状所生成路径的开销）来修复。

版本 1.0.0-alpha04

2023 年 12 月 13 日

发布了 androidx.graphics:graphics-shapes:1.0.0-alpha04、androidx.graphics:graphics-shapes-android:1.0.0-alpha04 和 androidx.graphics:graphics-shapes-desktop:1.0.0-alpha04。版本 1.0.0-alpha04 中包含这些提交内容。

新功能

• 此版本包含多项 API 变更以及 bug 修复。
• 许多 API 更改使 Shapes 库与 KMP 兼容。这样可以更轻松地从非 Android 代码（例如与 Android 无关的 Compose 代码）进行调用。例如，该 API 中没有 Android 类型（如之前的 PointF、矩阵和路径类型）。
• 出于性能原因，我们还对 API 和实现进行了多项更改，特别是为了最大限度地减少对象分配（和收集）。例如，从 PointF 迁移到单独的浮点参数可避免分配许多临时 PointF 结构来保存这些顶点。

API 变更

• 将 Morph.asMutableCubics 替换为用于遍历 MutableCubics 的函数。更改了 PointTransformer 函数接口，现在它接受 Point 的 x 坐标和 y 坐标，并返回 TransformedResult（使用转换后的 x 和 y 坐标构造）(I6719e)
• 移除了公共 Cubic 构造函数，并将其设为工厂函数。（I409ce）
• 添加了特定于 Android 的转换和绘制 API（I079f6、b/292289543）
• 消除 Android 依赖项（Iadc1c、b/292289543）
• 锚点和控件属性名称现在更合理（If13bd、b/294562941）
• PointF 参数已更改为 Float 对（Id4705、b/276466399、b/290254314）
• progress 现在会直接传递给 Morph 绘制命令 (Icdca2)

bug 修复

• 修复了创建大形状时出现的 bug。（I4fd66、b/313497325）

版本 1.0.0-alpha03

2023 年 6 月 7 日

发布了 androidx.graphics:graphics-shapes:1.0.0-alpha03。版本 1.0.0-alpha03 中包含这些提交内容。

API 变更

• 添加了新的 RoundedPolygon.rectangle() 函数（I78e7e、b/280322189）
• Star 和 Circle 函数现在会被去头处理，并通过 RoundedPolygon 的伴生对象进行调用：例如RoundedPolygon.star(...)(I14735)

bug 修复

• 修复了有关平滑的错误 (Ibf894)
• 修复了起始形状和结束形状相同时出现的 bug。更好地将可用空间分配在切割画面上，首先利用可用空间进行舍入，然后在剩余空间的情况下进行平滑处理。（Ibd320、b/277936300）

版本 1.0.0-alpha02

2023 年 4 月 19 日

发布了 androidx.graphics:graphics-shapes:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

API 变更

• Polygon 父类已与其子类 RoundedPolygon 合并；现在，所有多边形都是（可选）圆角多边形。
• Star 函数（仍像以前一样返回 RoundedPolygon）现在接受 innerRadius 值，而不是之前的 innerRadiusRatio 参数。此参数与现有 radius 参数使用相同的单位，从而使情况变得更简单、更一致。此外，numOuterVertices 参数已重命名为 numVerticesPerRadius，以指明相同数字同时应用于内外半径。
• CornerRounding.radius 之前记录为相对于多边形的大小，但它是（并且应该是）绝对值，而不是相对值。更新了文档，并修复了将最大值限制为 1.0 的注释。

版本 1.0.0-alpha01

2023 年 4 月 5 日

Graphics-Shapes 是一个新库，可让您轻松创建和渲染圆角多边形形状，以及不同形状之间的简单自动变形（动画）。

发布了 androidx.graphics:graphics-shapes:1.0.0-alpha01。此版本是从内部分支发布的。

新功能

• 使用 Polygon API 可创建具有所需顶点数的正多边形和星形多边形。
• 使用可选的 CornerRounding 参数来指定角的圆角半径和平滑参数，从而生成具有圆角的多边形形状。
• 使用新的 Morph(Polygon, Polygon) API 自动计算“变形”形状，其进度可以在 0 到 1 之间设置，以便在起始形状和结束形状之间添加动画效果。不断添加动画效果，在每一帧上绘制结果，在这些新的圆角形状之间创建流畅的动画。

Graphics Path 版本 1.0

版本 1.0.1

2024 年 5 月 1 日

发布了 androidx.graphics:graphics-path:1.0.1。版本 1.0.1 中包含这些提交内容。

bug 修复

• 改进了编译器标记。

版本 1.0.0

2024 年 3 月 6 日

发布了 androidx.graphics:graphics-path:1.0.0。

版本 1.0.0-rc01

2024 年 2 月 21 日

发布了 androidx.graphics:graphics-path:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

bug 修复

• 改进 PathIterator 在 API 上的性能34 (Id4629)

版本 1.0.0-beta02

2024 年 1 月 10 日

此版本中的更改都是关于缩减库的大小，由于原生代码做出的假设，其大小超过了必要的大小。

发布了 androidx.graphics:graphics-path:1.0.0-beta02。版本 1.0.0-beta02 中包含这些提交内容。

bug 修复

• 将 libandroidx.graphics.path.so 的大小缩减了 96%。（I71397）
• 将 libandroidx.graphics.path.so 的大小缩减 5%。（I2da7c）
• 将 androidx.graphics:graphics-path 的原生组件缩减了 43%。（I8e40d）

版本 1.0.0-beta01

2023 年 11 月 29 日

发布了 androidx.graphics:graphics-path:1.0.0-beta01。版本 1.0.0-beta01 中包含这些提交内容。

API 变更

• 移除了实验性 isAtLeastU() API 的使用（Ie9117、b/289269026）

bug 修复

• 修复了各种问题并提升了性能，包括该库如何处理圆锥曲线。

版本 1.0.0-alpha02

2023 年 6 月 7 日

发布了 androidx.graphics:graphics-path:1.0.0-alpha02。此版本是在内部分支中开发的。

注意： 此版本将仅基于 Android 14 (Upside Down Cake) Beta 1 SDK 或更高版本进行编译。

新功能

• 修复了内部平台版本检查在 Android 14 预览版上运行时出现问题的问题（版本检查会失败，但尤其是在 Android 14 上，版本检查的机制无法正常工作）。

版本 1.0.0-alpha01

2023 年 3 月 22 日

发布了 androidx.graphics:graphics-path:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

新功能

• 这个新库允许通过新的 PathIterator API 查询路径数据。利用此 API，调用方可以遍历 Path 对象的所有线段，以确定这些线段的操作和数据。
• 该库使用 Android 14 预览版中引入的类似 API，但此 AndroidX 版本的 API 也适用于低至 API 21 的版本。

Graphics Core 版本 1.0

版本 1.0.1

2024 年 9 月 4 日

发布了 androidx.graphics:graphics-core:1.0.1。版本 1.0.1 中包含这些提交内容。

bug 修复

• 修复了有时无法释放内存资源的问题。

版本 1.0.0

2024 年 5 月 29 日

发布了 androidx.graphics:graphics-core:1.0.0。版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

• 图形核心库的官方稳定版本。从 1.0.0-rc01 开始，修复了一些次要 bug 并提升了性能

版本 1.0.0-rc01

2024 年 4 月 17 日

发布了 androidx.graphics:graphics-core:1.0.0-rc01。此版本是在内部分支中开发的。

bug 修复

• 修复了导致在某些搭载 Android 14 的 Android 设备上，使用 CanvasBufferedRendererAPI 时可能会重复关闭文件描述符的问题。
• 修复了 FrameBuffer 无法正确删除帧缓冲区实例的问题。

版本 1.0.0-beta01

2023 年 12 月 13 日

发布了 androidx.graphics:graphics-core:1.0.0-beta01。版本 1.0.0-beta01 中包含这些提交内容。

新功能

• 引入了新的 LowLatencyCanvasView API，以支持在 View 层次结构中使用 Android 的 2D 图形 API (Canvas + Paint) 实现低延迟渲染。
• 引入了 CanvasBufferedRenderer API，以支持对 HardwareBuffer 进行硬件加速 Canvas 渲染。这可用于将界面的一部分绘制到缓冲区中，而缓冲区可使用 Bitmap.wrapHardwareBuffer API 转换为位图。

API 变更

• 更新了 CanvasBufferRenderer#releaseBuffer API，以包含可选的围栏参数。更新了文档，以说明何时返回 RenderResult#fence。(If1ea7)
• 向 RenderRequest 添加了 draw 方法，以支持利用协程来调度绘制请求。将之前使用执行器的绘制方法重命名为了 drawAsync。将 isClosed() 方法重构为属性。（I5bff6）
• 向 CanvasFrontBufferRenderer 公开了缓冲区格式参数，以直接映射到 CanvasBufferedRenderer.Builder#setBufferFormat (I0f272)
• 创建了 CanvasBufferedRenderer API，用于将硬件加速画布渲染处理到 HardwareBuffer 中。这会将实现向后移植到 Android Q，并配置交换链深度为 HardwareBuffers。ColorSpace 配置仍仅限于 Android U 及更高版本，不过 compat 实现可在开发者的。（I9b1d8）
• 向 SurfaceControlCompat.Transaction 添加了 setFrameRate/clearFrameRate API，以便控制帧速率以及实现无缝过渡或默认过渡的更改策略。（I6045c）
• 将 setDataSpace 所需的 API 级别从 Android T 降低到了 Android Q。（I59c34）
• 向 GLFrameBufferRenderer API 添加了 onBufferReleased 回调，让使用方有机会在不再提供缓冲区时清理状态 (I8a4e2)
• 创建 LowLatencyCanvasView 以支持以低延迟渲染与 View 层次结构渲染同步的内容的简单用例。这样，通过在内部管理 SurfaceView 实例，分别实现同步渲染和低延迟渲染，从而降低了与 SurfaceView 管理相关的复杂性。（I9253b）
• 向 CanvasFrontBufferedRenderer API 添加了色彩空间配置支持。更新了多缓冲区回调，以还包含返回缓冲的 SurfaceControl (I24bd9)

版本 1.0.0-alpha05

2023 年 9 月 6 日

发布了 androidx.graphics:graphics-core:1.0.0-alpha05。版本 1.0.0-alpha05 中包含这些提交内容。

新功能

• 引入了 GLFrameBufferRenderer API。它提供 OpenGL 依赖项、交换链配置、像素格式和 SurfaceControl 配置的组合。（Ic775b）

API 变更

• 向各种回调 API 添加了宽度 + 高度参数，以从 SurfaceHolder#Callbacks 获取竖线尺寸。（I7f9fc）
• 添加了清晰的 API，以清除前端和多缓冲层。（Ic1f95）
• 添加了对配置 GLFrontBufferedRenderer 中使用的交换链底层缓冲区类型的支持。（I07a13）
• 为 GLFrameBufferRenderer 的 getter、针对最大缓冲区条目的 IntRange 注解以及分别为 setFormat/setUsage 的 HardwareBufferFormart 和 HardwareBufferUsage 注解添加了 kotlin 属性。（Ief89e）
• 更新了 SurfaceControl 事务上的 setBuffer API，以提供释放栅栏。（Ice1bb）
• 添加了 SurfaceControlCompat.Transaction API，用于配置数据空间以及设置扩展的亮度范围。（Ic378d）

版本 1.0.0-alpha04

2023 年 6 月 7 日

发布了 androidx.graphics:graphics-core:1.0.0-alpha04。版本 1.0.0-alpha04 中包含这些提交内容。

新功能

• 引入了 CanvasFrontBufferedRenderer，以利用 android.graphics.Canvas API 和现有的 OpenGL 实现来支持低延迟图形

API 变更

• 更新了 SurfaceControlCompat.Transaction#setBuffer API，以允许可为 null 的 HardwareBuffer 实例镜像相应的平台 API (I173d7)
• 将引用双缓冲区渲染的方法重命名为多缓冲区，因为后备交换链可能包含 2 个以上的缓冲区。（I830d7）
• 创建 CanvasFrontBufferedRenderer API，使 3ps 能够使用 Canvas API 来利用前端缓冲渲染系统。（Ibfc29）

bug 修复

• 修复了在恢复相应 activity 后 GLFrontBufferedRenderer 无法呈现内容的问题。
• 修复了前端缓冲内容过早清除的问题。
• 修复了在低延迟图形 API 发布后不会移除 SurfaceHolder.Callbacks 的问题。

版本 1.0.0-alpha03

2023 年 3 月 22 日

发布了 androidx.graphics:graphics-core:1.0.0-alpha03。版本 1.0.0-alpha03 中包含这些提交内容。

API 变更

• 更新了 GLFrontBufferedRenderer 回调实现，以提供包含缓冲区宽度/高度的 BufferInfo 对象，以及可用于在渲染到中间暂存缓冲区后重新定位原始目的地的帧缓冲区标识符。（I7fe20）
• 将 SyncFence 创建操作整合为 SyncFenceCompat 上的静态出厂方法。
• 移除了 eglDupNativeFenceFDANDROID 的公共兼容性方法，改为使用 SyncFenceCompat 工厂方法来创建 SyncFence。这是为了确保无论 API 级别如何，所有 API Surface 都能获得正确的 SyncFence 实现。（I849bb）
• 添加了有关 FrameBufferRenderer 和 SyncStrategy 的文档。
  • 已将 FrameBufferRenderer + FrameBuffer + FrameBufferPool 移至 androidx.graphics.opengl 软件包
  • 将 SyncStrategy 移到了 androidx.graphics.opengl 软件包中
  • 已更新 RenderCallback#onDraw 个文档
  • 更新了 RenderCallback#obtainFrameBuffer 文档，其中 API 实现者负责调用 FrameBuffer.close
  • 更新了 onDrawComplete，以指明使用方负责分派要显示的内容
  • 将 SyncFence 兼容性接口/类移到了 androidx.hardware 软件包中，以镜像框架
  • 将 SyncFence API 重命名为了 SyncFenceV19，并将其设为私有，以便将用法整合到 SyncFenceCompat，后者会尽可能利用框架的 SyncFence API。（I5149c）
• 添加了 GLFrontBufferedRenderer#cancel 和 GLFrontBufferedRenderer#execute 方法。前者适用于应对防手掌误触的情况，此时应取消渲染到前端缓冲区并隐藏前端缓冲区。后者对于在 GL 线程上操控对象而无需调度渲染非常有用。(If0b7f)
• 添加了用于直接渲染到双缓冲层的 API。这有助于在恢复后重新渲染场景，也让消费者有机会根据要渲染的场景动态选择何时使用前端缓冲渲染。（Ied56c）
• 向 SurfaceControlCompat.Builder 添加了新的 API，以支持通过 SurfaceView 的现有机制配置另一个 SurfaceControl 实例的父级 SurfaceControl。（I1d1b6）
• 更多已废弃隐藏函数的返回值类型可为 null (Ibf7b0)
• 添加了 EGL_ANDROID_get_native_client_buffer 扩展常量，用于查询 Android 设备是否支持将 HardwareBuffer 实例导入可作为 EGLImage 实例使用的 EGLClientBuffer 对象。（Iad767）
• 添加了 @JvmDefaultWithCompatibility 注解 (I8f206)

版本 1.0.0-alpha02

2022 年 11 月 9 日

发布了 androidx.graphics:graphics-core:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

API 变更

• 修复了 Android S 中引入的 addTransactionCommitListener 缺少 RequiresApi 注解的问题 (I0a035)
• 更新了 onDraw<Front/Double> 缓冲区回调，以提供转换矩阵，除了当前缓冲区宽度/高度之外，使用方还可以传递给其顶点着色器。使用方负责使用这些参数正确预旋转其 OpenGL 渲染代码。(I82f9e)

bug 修复

• 通过在发出 SurfaceControl 事务之前预旋转缓冲区，缩短了图形延迟时间。
• 修复了错误日志会显示错误 300d (EGL_BAD_SURFACE) 的问题。
• 修复了 GLFrontBufferedRenderer 在其使用的对应 activity 被恢复后会失效的问题。
• 增加了对模拟器和 ChromeOS 设备的支持。
• 修复了前缓冲层可能会过早隐藏的问题。

版本 1.0.0-alpha01

2022 年 10 月 24 日

发布了 androidx.graphics:graphics-core:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

新功能

• 添加了图形核心 AndroidX 库的初始版本。其中包括支持低延迟用例（如触控笔输入）的 API。还引入了一些应用于 OpenGL 的帮助程序 API。

API 变更

• 引入了 GLFrontBufferedRenderer，用于协助前端和多缓冲区渲染，以实现低延迟和高质量的渲染输出。
• 引入了 GLRenderer API，用于协助各种 Surface 提供程序（如 SurfaceView、TextureView 等）实现 OpenGL 渲染。