Detailed explanation of Android's official Kotlin-First image loading library

Preface

Coil is a very young image loading library. It only released version 1.0.0 on October 22, 2020, but it has been promoted by Android officials. We talked about it in a blog post called Android Developers Backstage. The reason for the promotion is simple: on the one hand, this library is really well made, and on the other hand, this library is written entirely in Kotlin and uses a lot of Kotlin features, especially coroutines. So Google says it will not give up Java, but in fact we all know it.

Coil's name comes from the first letters of Coroutine Image Loader. It can be seen that images are loaded through Kotlin coroutines. The features are as follows:

• Faster: Coil has many performance optimizations, including memory caching and disk caching, saving thumbnails in memory, recycling Bitmaps through BitmapPool, automatically pausing and canceling network requests, etc.
• More lightweight: Coil has only 2,000 methods, which is about the same as Picasso. It is much lighter than Glide and Fresco.
• Easier to use: Coil's API makes full use of Kotlin's new features and has rich extension functions, which simplifies and reduces a lot of boilerplate code.
• More popular: Coil is developed in Kotlin and uses many popular open source libraries including Coroutines, okhttp, okio and AndroidX Lifecycles

From the features of Coil, we can see that it is a very suitable image loading library for personal apps, especially apps developed in pure Kotlin. Moreover, Coil uses a lot of new features and coroutines of Kotlin, which is of great value for us to learn Kotlin. Compared with glide and fresco, which have very complex structures and amazing amounts of code, Coil has only about 2,000 methods, so it is also very suitable for source code research and learning.

Basic Use

Coil can be downloaded from mavenCentral():

 implementation( "io.coil-kt:coil:1.1.1" )

Coil adds a lot of extension functions to ImageView, so we can load images with just one line of code:

 // URL
 imageView.load ( "https://www.example.com/image.jpg" ) 
 
 // Resource
 imageView. load (R. drawable. image) 
 
 // File
 imageView.load (File( "/path/to/image.jpg" ))

At the same time, we can also use lambda syntax to easily configure image loading:

 imageView.load ( "https://www.example.com/image.jpg" ) {
 crossfade( true )
    placeholder(R.drawable.image)
    transformations(CircleCropTransformation())
 }

Commonly used APIs

ImageLoader

ImageLoader is the steward of image loading in Coil, responsible for handling cache, data acquisition, image decoding, request management, Bitmap cache pool, memory management, etc. It is generally recommended to create only one ImageLoader and share it in the App, so that the performance is optimal. This is because each ImageLoader has its own memory cache and Bitmap cache pool.

We can create and configure ImageLoader through the constructor.

 val imageLoader = ImageLoader.Builder(context)
    .availableMemoryPercentage(0.25)
 .crossfade( true )
 .build()

At the same time, since ImageLoader is an interface, it means that we can test it very conveniently. For example, we can inject a fake ImageLoader to return the same drawable every time.

 val fakeImageLoader = object : ImageLoader { 
 
    private val drawable = ColorDrawable(Color.BLACK) 
 
    override fun enqueue(request: ImageRequest): Disposable {
        request.target?.onStart(drawable)
        request.target?.onSuccess(drawable)
 return disposable
 } 
 
    override suspend fun execute (request: ImageRequest): ImageResult {
 return SuccessResult(
            drawable = drawable, request = request,
            metadata = ImageResult.Metadata(
                memoryCacheKey = MemoryCache.Key ( "" ),
                isSampled = false ,
                dataSource = DataSource.MEMORY_CACHE,
                isPlaceholderMemoryCacheKeyPresent = false  
 )
 )
 }
 }

ImageRequest

ImageRequest provides all the necessary information for ImageLoader to load images, and we can also use custom Target for processing.

 val request = ImageRequest.Builder(context)
    .data( "https://www.example.com/image.jpg" )
 .target { drawable ->
 // Handle the result.
 }
 .build()
 context.imageLoader.enqueue(request)

ImageRequest is created based on the Builder mode, which includes various configuration items for loading images. Here we focus on the most commonly used configuration items.

Disposable

Disposable is the return value after calling the load() method, which is mainly used to cancel image loading:

 interface Disposable { 
 
 /**
 * Returns true if the image loading request has been completed or canceled  
 */
 val isDisposed: Boolean 
 
 /**
 * Cancel the ongoing image loading request and release related resources, and this method is idempotent
 */
 fun dispose() 
 
 /**
 * Non-blocking wait for task completion
 */
 @ExperimentalCoilApi
 suspend fun await()
 }

Image Transformation

Image transformation is a very common function in image loading libraries. Coil abstracts it into a Transformation interface. You can see that there is a BitmapPool parameter in the transform() method. This is because a Bitmap is often required when implementing graphic transformation. In this case, it can be directly obtained from the BitmapPool, thereby reusing the existing Bitmap.

 interface Transformation {
 fun key (): String
    suspend fun transform(pool: BitmapPool, input: Bitmap, size : Size ): Bitmap
 } 
 
 imageView.load ( "https://www.example.com/image.jpg" ) {
    transformations(CircleCropTransformation())
 }

Coil mainly provides the following image transformation effects:

Functional expansion

Coil not only provides many necessary functions, but also reserves many extension points for developers to customize. Coil's image loading mainly includes four main modules:

Interceptors

Coil's Interceptor undoubtedly draws on the design ideas of okhttp, which greatly facilitates subsequent function expansion. For example, we can add a custom cache layer to Coil:

 class CustomCacheInterceptor(
    private val context: Context,
    private val cache: LruCache<String, Drawable>
 ) : Interceptor { 
 
    override suspend fun intercept(chain: Interceptor.Chain): ImageResult {
        val value = cache.get(chain.request.data.toString())
 if (value != null ) {
 return SuccessResult(
                drawable = value.bitmap.toDrawable(context),
                request = chain.request,
                metadata = TODO()
 )
 }
 return chain.proceed(chain.request)
 }
 }

Mappers and Fetchers

When calling load() externally, the passed String parameter may point to a local resource file or a network image. Mappers and Fetchers can be used together to distinguish resource types. For example:

 imageView.load ( "android.resource://example.package.name/drawable/image " )
 imageView.load ( "https://www.example.com/image.jpg" )

StringMapper will convert the incoming String into the corresponding Uri.

 internal class StringMapper : Mapper<String, Uri> {
    override fun map(data: String) = data.toUri()
 }

ResourceUriFetcher will determine whether the scheme type of Uri is android.resource. If it is, it represents a local resource file, while HttpUriFetcher will determine whether the scheme of Uri is http or https. If it is, it represents a network image.

 internal class HttpUriFetcher(callFactory: Call.Factory) : HttpFetcher<Uri>(callFactory) {
    override fun handles(data: Uri) = data.scheme == "http" || data.scheme == "https"  
    override fun key (data: Uri) = data.toString()
    override fun Uri.toHttpUrl(): HttpUrl = HttpUrl.get(toString())
 }

Decoders

Android supports many image formats, but there are also many formats that it does not support (for example: Gif, SVG, video frames, etc.), so Coil provides a corresponding extension library.

① Gif (GifDecoder supports all API levels, but is slower, ImageDecoderDecoder loads faster, but is only available on API 28 and higher)

 implementation( "io.coil-kt:coil-gif:1.1.1" ) 
 
 val imageLoader = ImageLoader.Builder(context)
 .componentRegistry {
 if (SDK_INT >= 28) {
 add (ImageDecoderDecoder())
 } else {
 add (GifDecoder())
 }
 }
 .build()

② SVG (If the requested MIME type is image/svg+xml, all SVGs will be automatically detected and decoded)

 implementation( "io.coil-kt:coil-svg:1.1.1" ) 
 
 val imageLoader = ImageLoader.Builder(context)
 .componentRegistry {
 add (SvgDecoder(context))
 }
 .build()

③ Video frame (only supports File and Uri)

 implementation( "io.coil-kt:coil-video:1.1.1" ) 
 
 val imageLoader = ImageLoader.Builder(context)
 .componentRegistry {
 add (VideoFrameFileFetcher())
 add (VideoFrameUriFetcher())
 }
 .build()