Make coil-gif multiplatform

[outadoc]

This PR intends to bring animated GIF support to iOS and other non-Android platforms. (see #2347)

A new AnimatedSkiaImageDecoder has been integrated in nonAndroidMain, largely based on @colinrtwhite's POC, with added support for looping GIFs.

Since Skia natively supports animated WebP, this new decoder also supports them. I've validated that with a test image in the sample app, but I haven't committed it. I'm not sure if other formats (HEIF?) could be supported; I couldn't find proper images to test, so for now the decoder won't try to decode them.

• The coil-gif artifact has been converted to Kotlin Multiplatform
• decodeUtils.kt has been moved to commonMain, while the rest of the code stays in androidMain
• apiDump has been run
• Tests have been run
• The documentation has been updated
• The changes have been tested on Android, iOS and Desktop in the sample app
• Buffer next frames in the background
• Support AnimatedTransformation in AnimatedSkiaImage and update docs
• Support extra options in AnimatedSkiaImage
• Write new Skia tests

iOS preview

ios.mp4

Desktop preview

Enregistrement.de.l.ecran.2024-10-26.a.17.11.45.mov

[outadoc]

@colinrtwhite Hi! Feel entirely free to make suggestions or even entirely take over the PR if you feel like it. As you can see, it's based on your POC, so it should be familiar. I'm a graphics newbie, so there's probably a lot to improve still -- but hopefully this helps the project 😄

[colinrtwhite]

Thanks! Added some comments that we'll need to tackle before merging. I can take those on after the Coil 3.1 release or feel free to take a stab at the changes if you'd like. We'll also need to add tests for this before we can merge it.

[colinrtwhite]

We should introduce a common function like AnimatedImageDecoderFactory (not sure about the naming) that automatically returns the right decoder factory implementation for the platform/API level. That way we could recommend:

val imageLoader = ImageLoader.Builder(context)
    .components {
        add(AnimatedImageDecoderFactory())
    }
    .build()

in the readme.

[colinrtwhite]

I think we can support this on all platforms by replacing android.graphics.Canvas with coil3.Canvas in AnimatedTransformation.

[colinrtwhite]

We'll need to pass through Options so we can add support for all the properties in coil3/gif/imageRequest.kt. I don't think we should ship this without adding support for those properties first.

[colinrtwhite]

I think we'll need to tweak this to something like bufferedFramesCount (pass 0 for disabled, Int.MAX_VALUE to buffer everything) since we'll need to update the implementation to buffer a few frames up front then buffer the rest just in time before we need to draw them.

We'll want to buffer X frames during the decode process then figure out how to get a CoroutineScope so we can decode the rest right after AnimatedSkiaImage.draw is called.

[outadoc]

@colinrtwhite Thank you for your feedback. I'll try to address it as much as I can 🙂

[outadoc]

I've written JVM tests and rewritten some of the code to fix issues. I'm pretty satisfied with how the PR is turning out, even if we could still add more tests, I'm sure.

[revonateB0T]

Is there any possibility to use natively allocated pixels buffer?
Although desktop jvm has larger heap size, I don't think store pixels in jvm heap is a good idea.
Moreover, buffer size is not changed, we could just use two or three buffer to do something like decode-render-swap, just like vulkan swapchain, this help us avoid allocating extra memory.

[colinrtwhite]

@revonateB0T Agreed, but let's tackle this as a follow up.

For buffer size we need to consume/buffer the ImageSource entirely inside Decode.decode. This is to prevent leaking underlying references (mostly to Coil's disk cache). Would that still work with decode-render-swap?

[revonateB0T]

For buffer size we need to consume/buffer the ImageSource entirely inside Decode.decode. This is to prevent leaking underlying references (mostly to Coil's disk cache).

That's not optimal, ImageDecoder will not comsume source fully as well for animated image, it requires the source is seekable instead.

And that's why it requires a ByteArray/File/ByteBuffer, they are both seekable & rewindable, ImageDecoder takes ownership(for fd, it calls dup) and requires source must not be modified during AnimatedImageDrawable's lifecycle.

[revonateB0T]

Load frames totally to memory at once is terrible, we can easily expect a OOM occurs(If we use jvm heap) or operating system not response(If we use native heap) or process get killed for some webp/gif have long durations & frames.
That's extremely terrible idea...

[colinrtwhite]

@revonateB0T Ah I see what you mean. I was talking about copying the undecoded data in Decode.decode so we can read it outside of that scope (similar to what we do in AnimatedImageDecoder. How do we solve this in a common way across platforms?

[revonateB0T]

@revonateB0T Ah I see what you mean. I was talking about copying the undecoded data in Decode.decode so we can read it outside of that scope (similar to what we do in AnimatedImageDecoder. How do we solve this in a common way across platforms?

Then yes, decode-render-swap works, but it's still not optimal to buffer whole source in memory if source is too large, we still need a file-backed source to reduce memory pressure on low end machine.

The problem is, dup a fd on Linux then close DiskCache Editor is fine, we can read the content of file even diskcache entry is deleted(See https://man7.org/linux/man-pages/man2/unlink.2.html)

If the name was the last link to a file but any processes still
have the file open, the file will remain in existence until the
last file descriptor referring to it is closed.

But things is different on Windows, we are not allowed to delete a file if it's opened?

[colinrtwhite]

@revonateB0T We can't use a file backed source as we don't know when the animated GIF is no longer used and we can't expect users to manually call a close method.

[revonateB0T]

@revonateB0T We can't use a file backed source as we don't know when the animated GIF is no longer used and we can't expect users to manually call a close method.

On Android, we use file source if maybeRewriteGifSource is disabled, the file is in diskcache. When limit exceeded, file will be automatically deleted w/o affect decoder, but it only works on Linux platform.

[colinrtwhite]

Yep, we can't rely on that behavior on all supported platforms. Also Skiko doesn't support streaming - all bytes need to be in memory.

[colinrtwhite]

@outadoc Removing these functions breaks binary compatibility. We'll have to keep them and mark them as hidden and delegate to the non-hidden versions similar to here. When users update Kotlin will automatically compile against the non-hidden functions.

[colinrtwhite]

Suggested change

	* Set the callback to be invoked at the start of the animation if the result is an animated drawable.
	* Set the callback to be invoked at the start of the animation if the result is an animated image.

[colinrtwhite]

Suggested change

	* Set the callback to be invoked at the end of the animation if the result is an animated drawable.
	* Set the callback to be invoked at the end of the animation if the result is an animated image.

[colinrtwhite]

Let's move this constant to AnimatedSkiaImageDecoder.Factory.Companion and make it public

[colinrtwhite]

Can we assert bufferedFramesCount is >= 0 (or maybe >= 1)?

[colinrtwhite]

This is awesome! Thanks for adding such high quality tests.

[colinrtwhite]

Great idea to pass a time source here. Copied it CrossfadePainter as well.

[colinrtwhite]

Can we import only compose.runtime here?

[colinrtwhite]

Let's add an option for decoderCoroutineContext to this class' constructor. We can pass the value from options.decoderCoroutineContext from our Decoder.

[colinrtwhite]

We should probably block if the current frame we're trying to draw isn't available yet. We don't need to wait for the whole decode job to complete, however. We can use runBlocking on non-JS, but might need to spin in a while loop on JS to block.

Skipping drawing the current frame if it's not available yet could make it appear like the GIF is disappearing randomly on slower devices. It'll be up to the library user to set bufferedFramesCount high enough that we don't end up blocking.

[colinrtwhite]

Thanks for documenting this 🙏🏻

[colinrtwhite]

@outadoc This excellent! The implementation looks great. Left a few more comment + we'll need to rebase. Afterwards we should be good to merge!

[outadoc]

Thank you for the feedback Colin, sorry I haven't been able to work on this for a while due to some personal stuff. I'll try to make progress on it soon-ish, but if someone wants to make updates in the mean time, feel free.

[masterQian]

Because I was in a hurry, I used your code, which can compile and run normally. However, I found that testing on Desktop (Windows/JVM) showed that WEBP animation consumes a lot of CPU and memory. I am a beginner and cannot solve it, but through Profile monitoring, I saw that the program only used 200M of memory but applied for 5-8G of memory. I don't think this is a memory leak, but I don't know what the reason is. Thank you!

version: coil3-3.0.4 + coil-gif-multiplatform