Add image.load_animation

[ankith26]

My take on the PR #2218

fixes #1054

While that PR did some nice work and set the base up for this work, I believe the general consensus was that image.load_animation should just be pretty barebones in terms of the API, just returning a python list of the frames, closely wrapping the underlying SDL function.
If we have a builtin AnimatedSurface API in pygame-ce, it could now be implemented in pure python and use this function internally, and that should be decoupled from image entirely.

Here is a simple example of how a GIF player would look like

import itertools
import pygame

pygame.init()

frames = pygame.image.load_animation("animated_sample.gif")
print(frames)

screen = pygame.display.set_mode(frames[0][0].size)

frames_cycle = itertools.cycle(frames)
while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            raise SystemExit

    frame, frame_duration = next(frames_cycle)
    screen.blit(frame, (0, 0))
    pygame.display.flip()
    pygame.time.wait(frame_duration)

Here is the example file being used:

[robertpfeiffer]

👍

[MyreMylar]

OK, LGTM 👍 I've tested the animation locally and it all looks good to me. I like the simple API - not much to argue about but easy for people to expand on further (as they do already when loading animations frame by frame).

For some reason github is having a moment with downloading pygame and breaking the MSYS build but other than that it all looks good to merge. I'll leave it for a bit longer to give everyone a chance to have a look at the API as it's new.

[damusss]

Tested locally, checked the code, looks immaculate and well explained, awesome New API sauce, thanks!
Not going to press the shiny green merge button either at the moment

[Starbuck5]

I would like to weigh in before this is merged, thank you.

[Starbuck5]

While that PR did some nice work and set the base up for this work, I believe the general consensus was that image.load_animation should just be pretty barebones in terms of the API, just returning a python list of the frames, closely wrapping the underlying SDL function.

I've been consistently pushing for load_animation -> AnimatedSurface. But I'm okay with this approach instead, given that you and others support it. It doesn't let perfect be the enemy of the good.

[ankith26]

I think if/when we are adding AnimatedSurface, we can just support

• AnimatedSurface.__init__(frames: list[tuple[Surface, int]]) (so AnimatedSurface(image.load_animation(...)) would be supported)
• For GIF/WEBP loading, we can have a classmethod shorthand AnimatedSurface.load(...) that is equivalent to the above.

This is more pythonic IMO, even if we wanted to discard this PR and go with the class only approach.

[Starbuck5]

In a similar vein, what do you think about bringing image things into the Surface class overall?

image.load -> Surface.load
image.tobytes -> Surface.tobytes

[ankith26]

Love that idea as well. The same would go for Surface.save as well IMO.

[Starbuck5]

Tested with the iconic animation from the last April fools' event, there is some issue with webp. Presumably this would be fixed by an update to https://github.com/libsdl-org/SDL_image/releases/tag/release-2.8.5

pygame-real-engine.zip

[Starbuck5]

I think this is good to go in now, although SDL image should be handled before next release.

[LeWolfYT]

Will there ever be support for saving animations?

[gresm]

@LeWolfYT Very unlikely, as SDL doesn't support it.

[damusss]

Will there ever be support for saving animations?

@LeWolfYT you could technically request this in the SDL library, which would make the chances of us adding it a lot higher

(if you do, make sure to follow lib-sdl's posting rules and check for duplicates before)