Add constant to parse Gif Loop Count and apply to repeatCount

[tgyuuAn]

• Play the count of plays of the GIF to the count of plays of the GIF itself. #1863

Key Changes

• Loop Count Handling: The loop count is a feature present exclusively in the GIF format among the three formats being considered (GIF, WebP, HEIF). This distinction is important because it affects how animations are processed and repeated. Among these formats, only GIF includes the concept of a loop count.

You can use this feature in your code as follows:

@Preview
@Composable
fun Test() {
    val customImageLoader = ImageLoader.Builder(LocalContext.current)
        .components {
            if (Build.VERSION.SDK_INT >= 28) {
                add(AnimatedImageDecoder.Factory())
            } else {
                add(GifDecoder.Factory())
            }
        }
        .build()

    val imageRequest = ImageRequest.Builder(LocalContext.current)
        .data(sample.common.R.drawable.ic_change_loop_count)
        .repeatCount(GIF_LOOP_COUNT)  // <---- This Constant
        .build()

    AsyncImage(
        imageLoader = customImageLoader,
        model = imageRequest,
        contentDescription = null,
        modifier = Modifier.size(100.dp),
    )
}

Parsing Logic for GIF

During the GIF parsing process, we utilized source.peek() to read the data again. This was necessary because the loop count needs to be accessed without consuming the original BufferedSource, ensuring that we can still read the data needed for further processing. Unfortunately, this reliance on peek() is a limitation and feels like a workaround in the parsing logic.

Handling Loop Count in AnimatedImageDecoder

In the AnimatedImageDecoder, the logic that applies the loop count is separate from the logic that consumes the ImageSource. Because of this separation, the wrapDrawable function now includes an additional parameter, loopCount. This design choice was unavoidable, as adding a setter to Options.repeatCount would not have sufficed for properly applying the loop count without compromising the integrity of the original image data.

If you have a better opinion, please tell me, and I will reflect it.

---

GIF Format Overview

The Graphics Interchange Format (GIF) consists of a structured file format that is primarily used for graphics and animations. Here’s a breakdown of its structure and the significance of the Application Extension block, particularly regarding the parsing of the loop count.

GIF Structure in Bytes

1. Header (6 bytes):

   • The GIF file begins with a header that indicates the format version:
     • GIF87a (6 bytes)
     • GIF89a (6 bytes) <--- Loop Count exists only in this format.

2. Logical Screen Descriptor (7 bytes):

   • This section provides information about the logical screen, including dimensions and color table flags.

3. Global Color Table (if present):

   • This table can contain up to 256 colors and is 3 bytes per color, resulting in a maximum size of 765 bytes (256 colors).

4. Image Descriptor (10 bytes):

   • Each image within the GIF is described by an Image Descriptor that includes its position and size on the logical screen.

5. Image Data:

   • This section contains the actual pixel data for the image, which may also include local color tables if specified.

6. Extension Blocks:

   • GIF files can include several extension blocks, which provide additional functionality.

Application Extension Block

The Application Extension Block is crucial for animated GIFs as it defines the animation properties, including the loop count. The structure of the Application Extension Block is as follows:

• Block Introducer (1 byte): Always 0x21 to indicate an extension block.
• Label (1 byte): Indicates the type of extension, 0xFF for application extension.
• Block Size (1 byte): Indicates the size of the application identifier (usually 0x0B for 11 bytes).
• Application Identifier (8 bytes): Typically "NETSCAPE".
• Application Authentication Code (3 bytes): Usually "2.0".
• Data Block Size (1 byte): Indicates the size of the data block that follows (typically 0x03 for three bytes).
• Loop Count Indicator (1 byte): Always 0x01, indicating the presence of loop count data.
• Loop Count (2 bytes): The actual loop count, specified in little-endian format. A value of 0 indicates infinite looping.
• Block Terminator (1 byte): Always 0x00 to indicate the end of the extension.

In our parsing logic, we focus on the Application Extension to extract the loop count, which is critical for controlling the animation behavior of the GIF.

internal fun extractLoopCountFromGif(source: BufferedSource): Int? {
    return try {
        val byteArray = source.use { it.readByteArray() } // Copy data
        val bufferedSource = byteArray.inputStream().source().buffer() // Create BufferedSource from the copy
        val loopCount = parseLoopCount(bufferedSource)
        loopCount
    } catch (e: Exception) {
        null
    }
}

private fun parseLoopCount(source: BufferedSource): Int? {
    // Read GIF header
    val headerBytes = ByteArray(6)
    if (source.read(headerBytes) != 6) return null

    // Read Logical Screen Descriptor
    val screenDescriptorBytes = ByteArray(7)
    if (source.read(screenDescriptorBytes) != 7) return null

    // Skip Global Color Table
    if ((screenDescriptorBytes[4] and 0b10000000.toByte()) != 0.toByte()) {
        val colorTableSize = 3 * (1 shl ((screenDescriptorBytes[4].toInt() and 0b00000111) + 1)) // Calculate color table size
        source.skip(colorTableSize.toLong()) // Skip Global Color Table
    }

    // Handle Application Extension Block
    while (!source.exhausted()) {
        val blockType = source.readByte().toInt() and 0xFF
        if (blockType == 0x21) { // Extension Introducer
            val label = source.readByte().toInt() and 0xFF
            if (label == 0xFF) { // Application Extension
                val blockSize = source.readByte().toInt() and 0xFF
                val appIdentifier = source.readUtf8(8)
                val appAuthCode = source.readUtf8(3)

                // Check for NETSCAPE block and parse loop count
                if (appIdentifier == "NETSCAPE" && appAuthCode == "2.0") {

                    // Read data block size
                    val dataBlockSize = source.readByte().toInt() and 0xFF
                    // Read loop count indicator byte
                    val loopCountIndicator = source.readByte().toInt() and 0xFF
                    // Read low and high bytes for loop count
                    val loopCountLow = source.readByte().toInt() and 0xFF // Read low byte
                    val loopCountHigh = source.readByte().toInt() and 0xFF // Read high byte
                    val loopCount = (loopCountHigh shl 8) or loopCountLow // Combine high and low bytes

                    // Read block terminator byte
                    val blockTerminator = source.readByte().toInt() and 0xFF
                    return if (loopCount == 0) Int.MAX_VALUE else loopCount // 0 means infinite loop
                } else {
                    skipExtensionBlock(source) // Skip if not NETSCAPE
                }
            } else {
                skipExtensionBlock(source) // Skip other extension blocks
            }
        }
    }
    return null
}

// Function to skip Extension Blocks
// Extension Blocks always terminate with a zero
private fun skipExtensionBlock(source: BufferedSource) {
    while (true) {
        val size = source.readByte().toInt() and 0xFF
        if (size == 0) break
        source.skip(size.toLong())
    }
}

---

For further reading, check out:

• Animated GIF
• What's in a GIF?

---

If I need to write test code, please let me know where I can write it.

@colinrtwhite

[revonateB0T]

You mean we need to skip over all image data for application extension block to parse loop count?
You use a peek buffer so almost all file content will be read into okio Buffer(art heap) (i.e. Buffer size will enlarged to file length, we cannot reuse Segment).
This may cause OOM and huge performance regression, we need to warn user that trade-off.

[tgyuuAn]

@revonateB0T

Ideally, it would be best to parse the Loop Count directly during the initial parsing of the GIF. However, currently, I have concluded that we need to use either peek() or clone() of BufferedSource.

Between these two methods, would it be better to use clone() to allow for garbage collection of the memory, rather than using peek()?

Or is the approach itself flawed?

I am quite concerned that the current implementation may not be the most efficient in terms of performance and memory management. I would appreciate any appropriate advice you could provide.

[revonateB0T]

You cannot clone a BufferedSource to another BufferedSource, as Source is one-shot.
It's hard to optimize it currently if we consist on that BufferedSource abstraction.
We need to break that, consider a ByteBuffer source which is seekable & rewindable, a File is seekable & rewindable, so I suggest you warn user we may OOM, let they know the trade-off.

[tgyuuAn]

Thank you so much for your advice. Let's think more about this !!

[revonateB0T]

Check if the source is gif before we peek it.

coil/coil-gif/src/main/java/coil3/gif/decodeUtils.kt

Line 26 in 05c7fe2

fun DecodeUtils.isGif(source: BufferedSource): Boolean {

[tgyuuAn]

I appreciate your insight!

[colinrtwhite]

@tgyuuAn Thank you for taking the time to write this! That said, I think this can be implemented without a custom GIF parser. The AnimatedImageDrawable docs mention that by default the repeat count in the encoded data is respected. As such I think all we need to do to support using the encoded repeat count is to not call animatedDrawable.repeatCount = if options.repeatCount == GIF_LOOP_COUNT. Also I would rename GIF_LOOP_COUNT to ENCODED_REPEAT_COUNT to indicate it's encoded in the data.

For GifDecoder I don't think we can support repeatCount without reading the data, but we can just mark ENCODED_REPEAT_COUNT as API >= 28. I'd prefer to avoid adding custom GIF parsing code since it would only be used on older devices and it could be tough to maintain long term.

[tgyuuAn]

@tgyuuAn Thank you for taking the time to write this! That said, I think this can be implemented without a custom GIF parser. The AnimatedImageDrawable docs mention that by default the repeat count in the encoded data is respected. As such I think all we need to do to support using the encoded repeat count is to not call animatedDrawable.repeatCount = if options.repeatCount == GIF_LOOP_COUNT. Also I would rename GIF_LOOP_COUNT to ENCODED_REPEAT_COUNT to indicate it's encoded in the data.

For GifDecoder I don't think we can support repeatCount without reading the data, but we can just mark ENCODED_REPEAT_COUNT as API >= 28. I'd prefer to avoid adding custom GIF parsing code since it would only be used on older devices and it could be tough to maintain long term.

I feel a weight lifted off my shoulders !!!!!!!

[tgyuuAn]

@colinrtwhite

If it is over 28, there is an exception that causes infinite repetition if you use GifDecoder.

[tgyuuAn]

In this part, the lint was broken because the version branch for ENCODED_LOOP_COUNT was not given, but this was fixed.

[colinrtwhite]

You'll have to run ./gradlew apiDump to update the latest API files since the change updates the public API.

[colinrtwhite]

I think we want to leave this check as is. ENCODED_LOOP_COUNT shouldn't be passed to MovieDrawable.setRepeatCount.

[colinrtwhite]

We'll need to add handling to GifDecoder.Factory to ensure we don't set the repeat count there either when options.repeatCount == ENCODED_LOOP_COUNT.

[tgyuuAn]

We'll need to add handling to GifDecoder.Factory to ensure we don't set the repeat count there either when options.repeatCount == ENCODED_LOOP_COUNT.

I'm trying to add check() to the Factory as shown below. What do you think about this?

class Factory(
    val enforceMinimumFrameDelay: Boolean = true,
) : Decoder.Factory {

    override fun create(
        result: SourceFetchResult,
        options: Options,
        imageLoader: ImageLoader,
    ): Decoder? {
        if (Build.VERSION.SDK_INT >= 28) {
            check(options.repeatCount == ENCODED_LOOP_COUNT) { 
                "ENCODED_LOOP_COUNT cannot be used with GifDecoder. Please use the AnimatedImageDecoder if you need to use the encoded loop count."
            }
        }

        if (!DecodeUtils.isGif(result.source.source())) return null
        return GifDecoder(result.source, options, enforceMinimumFrameDelay)
    }
}

[colinrtwhite]

We only want to guard against it here and ignore the parameter instead of throwing: https://github.com/coil-kt/coil/blob/main/coil-gif/src/main/java/coil3/gif/GifDecoder.kt#L52

[colinrtwhite]

I think we should move this constant to AnimatedImageDecoder.Companion.ENCODED_LOOP_COUNT because it's only supported there and can't be used by MovieDrawable.

[tgyuuAn]

Thx, that's a really good idea.

[colinrtwhite]

@tgyuuAn You need to run ./gradlew spotlessApply to fix the style check.

[colinrtwhite]

We can remove this annotation as AnimatedImageDecoder already has it.

[colinrtwhite]

Suggested change

* This only applies when using [AnimatedImageDecoder].

[tgyuuAn]

I updated it !

[colinrtwhite]

@tgyuuAn Thanks for implementing this - no more changes needed! I'll merge this once we're done with 3.0.x bug fix releases and include it in the 3.1.0 release.