Swift Concurrency ベースの画像読み込みライブラリ Vulp

ビューと連携し、表示に必要な画像を非同期に読み込む。

Swift Concurrency ベースの画像読み込みライブラリ Vulp を開発しています。DAWN for Mastodon で、画像の表示に使っています。

画像のダウンロード、デコード、リサイズ、キャッシュに加え、SwiftUI・UIKit での表示に対応しています。静止画だけでなく、GIF・APNG・WebP のアニメーションや、動画のサムネイルも扱えます。

Vulp は、画像を描画するビューとの連携を重視して設計しています。主に意識しているのは、次の3点です。

DAWN のタイムラインには、投稿の画像やアバター、カスタム絵文字が並びます。同じ画像が繰り返し表示されたり、複数の絵文字がアニメーションしたりする画面で、これらの仕組みを使っています。

以下は、DAWN でアニメーション画像を含む大量のカスタム絵文字をスクロールしている様子です。この録画では、スクロールが引っかからずに動いていることを確認できます。

アニメーションするカスタム絵文字を並べた一覧。Vulp で画像を読み込み、表示しています。

MainActor で画像処理をしない

Vulp では、画像の取得、デコード、リサイズ、キャッシュへのアクセスを MainActor から切り離しています。画像の準備中も、スクロールやタップへの応答を妨げないためです。MainActor では、読み込み結果を受け取って表示を更新します。

MainActorで表示サイズの確認、リクエスト作成、Taskの開始とキャンセル、画像の設定を行う。画像の読み込みはMainActorから離し、キャッシュや共有リクエストは専用actor、デコードやリサイズはconcurrentな処理として実行する。
ビューに関わる処理は MainActor で行い、画像の読み込みや処理を分離しています。キャッシュなどの共有状態は専用の actor で管理します。

この設計のトレードオフとして、ビューの最初の描画フレームで画像が表示されないことを許容しています。キャッシュに画像がある場合も、同期的に取り出して表示するのではなく、非同期に取得してから表示を更新します。

ビューのサイズに合わせてデコードする

Vulp の画像ビューは、表示サイズと画面の倍率から、画像の読み込みに必要なピクセル数を求めます。たとえば、150 pt 四方のビューを 3x の画面で表示する場合は、450 × 450 px を基準にします。呼び出し側でサイズを計算して渡す必要はありません。

このサイズに合わせて、デコード時に画像を縮小します。小さなアバターを表示する場合も、元画像をフルサイズでデコードすることを避けられます。

レイアウトが変わった場合は、新しい表示サイズに合わせて画像を読み込みます。読み込みが終わるまでは、それまでの画像を表示し続けます。

また、わずかなサイズの違いでキャッシュが分かれないよう、要求サイズを一定の段階に丸めています。近いサイズのビューなら同じ画像を再利用でき、サイズ変更に伴うデコードやリサイズの回数を減らせます。

ビューの表示サイズと画面の倍率から画像をリクエストし、キャッシュの確認、取得、デコード、リサイズを経て表示する流れ。
ビューが表示サイズに応じた画像をリクエストします。デコード済みの画像はメモリに、元データはディスクにキャッシュします。

同じ画像を別のサイズで表示する場合も、ディスクに元データがあれば、再ダウンロードせずにデコードできます。

同じ画像の読み込みを共有する

Swift Concurrency を使った実装の例として、Utils/TaskDeduper.swift を紹介します。同じ画像が複数のセルに表示されるときに、読み込みを一つにまとめるための仕組みです。

二つのセルが同じ読み込み Task の結果を待つ。セル A がキャンセルされてもセル B のために読み込みを継続し、完了時に結果を返す。
セルごとに待機をキャンセルできます。共有する読み込み Task は、待機しているセルがなくなったときにキャンセルします。

以下は、処理を共有する部分の抜粋です。

let (flight, isLeader) = await join(key)
if isLeader {
    let operationTask = Task(priority: priority) {
        do {
            await flight.complete(.success(try await operation()))
        } catch {
            await flight.complete(.failure(error))
        }
        remove(key, flight: flight)
    }
    await flight.install(operationTask)
}
return try await flight.value()

join(key) は、同じキーの処理が実行中なら、その処理を表す flight を返します。新しく処理を作った場合だけ isLeader が true になり、Task を開始します。後続の呼び出しは、同じ flight の結果を待ちます。キーごとの処理は actor 内で管理しています。

処理が完了すると、待機中の各呼び出しに結果を返し、管理対象から外します。キャッシュとは別に、実行中の処理の重複を防ぐ仕組みです。

キャンセルは呼び出しごとに扱います。たとえば、二つのセルが同じ画像を読み込んでいるときに、一方が画面外に出ても、もう一方の読み込みは継続する必要があります。

private func cancel(_ waiterID: UUID) {
    waiters.removeValue(forKey: waiterID)?
        .resume(throwing: CancellationError())

    if waiters.isEmpty, result == nil {
        isCancelled = true
        operationTask?.cancel()
    }
}

キャンセルされた呼び出しには CancellationError を返します。ほかに待機中の呼び出しがあれば、共有している処理は継続します。待機している呼び出しがなくなった時点で、処理の Task もキャンセルします。

これにより、複数のセルで読み込みを共有しながら、セル単位でキャンセルできます。全体のコードは TaskDeduper.swift にあります。

アニメーションのフレームを先読みする

アニメーション画像は、再生に合わせてフレームをデコードします。標準では、現在のフレームに加えて次の3フレームを先読みします。

フレーム3の表示中は4・5・6を先読みする。フレーム4に進むと先読み範囲も移動し、新たにフレーム7を読み込む。
再生に合わせて先読み範囲を更新します。範囲外になったフレームも、画像キャッシュに残る場合があります。

先読みするフレーム数は変更できます。デコードしたフレームは静止画と同じ画像キャッシュにも保存するため、メモリ使用量は先読み数とキャッシュの設定で調整します。

リポジトリの Example.swiftpm には、アニメーション画像を並べたグリッドや動画サムネイルのサンプルを用意しています。メディアも同梱しているので、手元で動かして試せます。

詳しい API や使用例は GitHub のリポジトリ にまとめています。