图形

图形

  

API 参考文档
androidx.graphics

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

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

制品	稳定版	候选版	Beta 版	Alpha 版
graphics-core	1.0.3	-	-	-
graphics-path	1.0.1	-	-	-
graphics-shapes	1.0.1	-	-	1.1.0-alpha01

此库的最后更新时间：2025 年 3 月 26 日

声明依赖项

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

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

Groovy

dependencies {
    implementation "androidx.graphics:graphics-core:1.0.3"
    implementation "androidx.graphics:graphics-path:1.0.1"
    implementation "androidx.graphics:graphics-shapes:1.1.0-alpha01"
}

Kotlin

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

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

反馈

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

创建新问题

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

此工件没有版本说明。

图形版本 1.1

版本 1.1.0-alpha01

2024 年 12 月 11 日

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

新功能

• 将主要演示改为了通用形状编辑器。这样，您就可以从 svg 路径导入形状，在自动流程中漏掉特征时手动修改检测到的特征，并将结果导出为可在生产代码中使用的代码。(I1ac13)
• 将形状轮廓进度的角度测量值替换为曲线长度测量值，这样就可以使用更复杂的形状进行变形。(I75478) , I390dd
• 改进了特征映射算法，因此更多变形效果看起来应该更自然。(I83287)

API 变更

• 添加了 SVG 路径导入和地图项序列化器。常规流程如下：
  • 使用新的 SvgPathParser.parseFeatures() 将 svg 路径（svg 的 path 元素上的 d 属性的值）转换为 List<Feature>。
  • 您可以对其进行修改，然后使用 FeatureSerializer.serialize() 将其序列化为字符串。
  • 生成的字符串可在生产代码中使用，只需使用 FeatureSerializer.parse() 导入即可
  • 请注意，第 1 步和第 2 步只需执行一次，并且可以使用新应用执行。正式版代码只需执行第 3 步。（I9bd00、b/371196190）、（Ic3842）、（If68ed）、（I10251）
• 公开多边形地图项和地图项类型。现在，您可以使用接受 List<Features> 的基本构造函数创建更通用的 RoundedPolygons。特征主要是一个立方贝塞尔曲线列表，但它们带有标记，以帮助“变形”算法在起始形状和结束形状之间进行匹配（凸角映射到凸角，凹角映射到凹角）。(I61e76)、(I1fc5c)
• 添加了对 watchosDeviceArm64 KMP 目标和目标 kotlin 1.9 的支持。（Icf15d、b/364652024）

bug 修复

• 修复了上一个地图项为空时的极端情况。(I390dd)
• 增强了 RoundedPolygon 创建功能的稳健性。（Ib862c、b/360888486）
• 修复了 RoundedPolygon 初始化方面的 bug。(I83ddb)
• 修复了用于估算多边形中心的算法中的错误。(Ida147)

图形形状 1.0 版

版本 1.0.0

2024 年 9 月 4 日

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

版本 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、Matrix 和 Path 类型。
• 出于性能方面的考虑，我们还对 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 修复

• 修复了平滑处理方面的 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 参数。此值与现有半径参数采用相同的单位，从而简化了操作并提高了一致性。此外，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，以便在起始形状和结束形状之间进行动画处理。为该进度添加动画效果，并在每一帧上绘制结果，以便在这些新的圆角形状之间创建流畅的动画。

图形路径版本 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 修复

• 改进了 API 低于 34 的 PathIterator 的性能 (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（翻转蛋糕）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 的版本。

图形核心版本 1.0

版本 1.0.3

2025 年 3 月 26 日

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

bug 修复

• 修复了在 API<33 的某些设备上绘制时出现的全屏闪烁问题。

版本 1.0.2

2024 年 10 月 16 日

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

bug 修复

• 修复了以下问题：即使 SurfaceControl 实例已释放，系统合成器仍会继续管理它们。
• 修复了以下问题：在低延迟依赖项被处置后，当前显示的 HardwareBuffer 实例不会被释放
• 修复了某些不支持前端缓冲区使用标志的 Android 14 及更高版本设备上的闪烁问题

版本 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 的 swapchain 深度配置。ColorSpace 配置仍仅限于 Android U 及更高版本，但兼容性实现会代表开发者提供无操作行为。(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 添加了 width + height 参数，以便从 SurfaceHolder#Callbacks 传输尺寸。(I7f9fc)
• 添加了清除 API，用于清除前端和多缓冲区图层。(Ic1f95)
• 添加了对配置 GLFrontBufferedRenderer 中使用的 swapchain 的底层缓冲区类型的支持。(I07a13)
• 分别为 GLFrameBufferRenderer 上的 getter 添加了 Kotlin 属性、为最大缓冲区条目添加了 IntRange 注解，并为 setFormat/setUsage 添加了 HardwareBufferFormart 和 HardwareBufferUsage 注解。(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，以允许 nullable HardwareBuffer 实例镜像相应的平台 API (I173d7)
• 将引用双缓冲区渲染的方法重命名为多缓冲区，因为后备交换链可能包含超过 2 个缓冲区。(I830d7)
• 创建了 CanvasFrontBufferedRenderer API，以便 3ps 能够使用 Canvas API 利用前端缓冲渲染系统。(Ibfc29)

bug 修复

• 修复了 GLFrontBufferedRenderer 在恢复相应 activity 后无法呈现内容的问题。
• 修复了前端缓冲内容会过早清除的问题。
• 修复了在发布低延迟图形 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 Surface 都能收到正确的 SyncFence 实现，无论 API 级别如何。(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)
• 除了通过 SurfaceView 的现有机制之外，还向 SurfaceControlCompat.Builder 添加了新 API，以支持通过其他 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 渲染。