圖像

圖像

  

API 參考資料
androidx.graphics

跨多個 Android 平台版本善用圖像設施

下表列出 androidx.graphics 群組的所有構件。

構件	穩定版	候選版	Beta 版	Alpha 版
圖形核心	1.0.0	-	-	-
圖形路徑	1.0.1	-	-	-
圖形形狀	-	1.0.0-rc01	-	-

本程式庫上次更新日期：2024 年 7 月 24 日

宣告依附元件

如要新增 Graphics 的依附元件，必須將 Google Maven 存放區新增至專案中。詳情請參閱「Google 的 Maven 存放區」。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

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

Kotlin

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

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

這個構件沒有任何版本資訊。

Graphics Shapes 1.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)
• 已將 calculateBounds() 函式新增至 Morph，以便在 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)

修正錯誤

• 將這些形狀繪製為筆劃路徑時，偶爾會出現算繪不自然的假影，這是因為與零長度曲線有關的低階轉譯問題。這項錯誤修正了，消除了所有長度為零的曲線 (這也因此能節省形狀產生的路徑額外負荷)。

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 變更並修正了一些錯誤。
• 許多 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)

修正錯誤

• 修正建立大形狀時發生的錯誤。(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)
• 「星號」和「圓形」函式現已解碼，並透過 RoundedPolygon 的隨附物件呼叫：例如RoundedPolygon.star(...)(I14735)

修正錯誤

• 修正平滑問題 (Ibf894)
• 修正開始和結束形狀相同時發生的錯誤。針對剪刀，進一步分配可用空間；首先使用可用空間進行四捨五入，如果空間不足，則能夠平滑處理。(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，以在開始和結束形狀之間建立動畫。以動畫呈現進度，在每個影格上繪製結果，在新的圓角形狀之間建立流暢的動畫。

Graphics Path 1.0 版

1.0.1 版

2024 年 5 月 1 日

發布 androidx.graphics:graphics-path:1.0.1。1.0.1 版包含這些修訂版本。

修正錯誤

• 改善編譯器標記。

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 版包含以下修訂項目。

修正錯誤

• 改善 API 中的 PathIterator 效能。34 (Id4629)

1.0.0-beta02 版

2024 年 1 月 10 日

這個版本中的變更主要是關於縮減程式庫大小，但該程式庫的大小超過原生程式碼的假設。

發布 androidx.graphics:graphics-path:1.0.0-beta02。查看 1.0.0-beta02 版的修訂項。

修正錯誤

• 已將 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)

修正錯誤

• 修正多項錯誤並提升效能，包括程式庫如何處理圓環。

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，但這個 API 的 AndroidX 版本也適用於 API 21 以上的版本。

Graphics Core 1.0 版

1.0.0 版本

2024 年 5 月 29 日

發布 androidx.graphics:graphics-core:1.0.0。1.0.0 版包含這些修訂版本。

1.0.0 的主要功能

• 圖形核心程式庫的官方穩定版。包含小錯誤修正和 1.0.0-rc01 版本的效能改善項目

1.0.0-rc01 版

2024 年 4 月 17 日

發布 androidx.graphics:graphics-core:1.0.0-rc01。這個版本是在內部分支版本中開發。

修正錯誤

• 修正問題：在某些搭載 Android 14 的 Android 裝置上，CanvasBufferedRendererAPI 可能導致檔案描述元發生雙重關閉問題。
• 修正 FrameBuffer 無法正確刪除 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 (畫布 + 繪製) 進行低延遲轉譯。
• 推出 CanvasBufferedRenderer API，以支援硬體加速畫布算繪至 HardwareBuffer。您可以使用此程式碼將部分使用者介面繪製成緩衝區，再利用 Bitmap.wrapHardwareBuffer API 轉換為點陣圖。

API 變更

• 更新 CanvasBufferRenderer#releaseBuffer API，加入選用的 Fence 參數。更新說明文件，說明傳回 RenderResult#fence 的時間。(If1ea7)。
• 將 draw 方法新增至 RenderRequest，以支援運用協同程式排定繪製要求。將先前使用執行程式的繪製方法重新命名為 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 新增 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，以支援在現有 OpenGL 實作與使用 android.graphics.Canvas API 的情況下，支援低延遲圖形

API 變更

• 已更新 SurfaceControlCompat.Transaction#setBuffer API，允許可為空值的 HardwareBuffer 執行個體反映對應的平台 API (I173d7)
• 將參照雙重緩衝區轉譯的方法改為多緩衝區，因為幕後交換鏈可能包含超過 2 個緩衝區。(I830d7)。
• 建立 CanvasFrontBufferedRenderer API，讓 3ps 透過 Canvas API 使用前端緩衝轉譯系統。(Ibfc29)。

修正錯誤

• 修正問題：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 物件，其中包含緩衝區寬度/高度，以及影格緩衝區 ID，以便在算繪到中繼暫存緩衝區後重新指定原始目的地。(I7fe20)。
• 在 SyncFenceCompat 上將 SyncFence 建立作業合併為靜態工廠方法。
• 移除 eglDupNativeFenceFDANDROID 的公開相容性方法，改用 SyncFenceCompat 工廠方法建立 SyncFence。這是為了確保無論 API 級別為何，所有 API 介面都能接收正確的 SyncFence 實作項目。(I849bb)。
• 已新增 FrameBufferRenderer 和 SyncStrategy 說明文件。
  • 已將 FrameBufferRenderer + FrameBuffer + FrameBufferPool 移至 androidx.graphics.opengl 個套件
  • 已將 SyncStrategy 移至 androidx.graphics.opengl 套件
  • 已更新 RenderCallback#onDraw 份文件
  • 更新了 RenderCallback#obtainFrameBuffer 說明文件，該說明文件負責呼叫 FrameBuffer.close
  • 更新 onDrawComplete，表示取用者有責任將內容分派來顯示
  • 將 SyncFence 相容性介面/類別移至 androidx.hardware 套件，以反映架構
  • 已將 SyncFence API 重新命名為 SyncFenceV19，並將 API 設為不公開，以便將使用情形整合到 SyncFenceCompat，盡可能運用架構的 SyncFence API。(I5149c)。
• 已新增 GLFrontBufferedRenderer#cancel 和 GLFrontBufferedRenderer#execute 方法。前者適用於防手掌誤觸的情況，應取消算繪前緩衝區，並隱藏前緩衝區。後者在各種情況下就很有用，可操控 GL 執行緒上的物件，而不必排定算繪時間。(If0b7f)。
• 新增 API，直接算繪至雙緩衝圖層。這有助於在繼續後重新轉譯情境，並讓消費者有機會根據所需算繪的場景，選擇性地決定使用前端緩衝轉譯的時機。(Ied56c)。
• 在 SurfaceControlCompat.Builder 中新增 API，以支援在 SurfaceView 的現有機制之外，從其他 SurfaceControl 執行個體設定父項 SurfaceControl。(I1d1b6)。
• 更多已淘汰隱藏函式的傳回類型為空值 (Ibf7b0)。
• 新增 EGL_ANDROID_get_native_client_buffer 擴充功能常數，以查詢 Android 裝置是否支援將 HardwareBuffer 執行個體匯入 EGLClientBuffer 物件，做為 EGLImage 執行個體使用。(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)。

修正錯誤

• 透過在發出 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 轉譯。