Implement `saveGif` as a native p5 function

[jesi-rgb]

trafficstars

🚧 This branch will be the work in progress for the implementation of the public saveGif function for the '22 GSoC edition. 🚧

Save Gif

This PR resolves issue #5118, in which a thorough discussion is had about whether p5.js should include a native GIF encoding solution or not.

How it works

In the previously mentioned issue some proposals were discussed about how the interface for this functionality should be. The easiest I found to both implement and use was the following. The saveGif function admits at most 3 arguments for now:

saveGif(filename, duration, delay)

• filename for the name of the file downloaded to your computer
• duration duration in seconds that you wish to download from your animation
• delay delay in seconds that you wish to wait before recording the animation. The animation will nevertheless have a duration of what you specified on the duration argument.

As an example, I think it is best to use it within the mouse/keyboard events:

 function mousePressed() {
   if (mouseButton === RIGHT) {
     saveGif('mySketch', 3, 1);
   }
 }

This function will take all the current frames of the present animation, save them in a buffer and then proceed to generate a palette, apply this palette to every frame, optimize for transparency and encode it in a GIF blob, that will then force to download.

Functionality can be extended in lots of places but I believe that the current state works very conveniently by adding just 3 extra lines of familiar code. I plan on keep contributing to this functionality even after the GSoC to make it as convenient as possible.

Changes

1. Most important change is in src/image/loading_displaying.js, which is where the main saveGif function lives. Alongside this function, the functions _generateGlobalPalette and _pixelEquals were also added.
2. Second important change is in src/image/image.js, where the old saveGif function was renamed to a more obscure and explicit encodeAndDownloadGif.
   1. Alongside this change, the file src/image/p5.Image.js was also changed to consider this new function name.
   2. Same goes with the test test/unit/image/downloading.js, which was updated to evaluate the encodeAndDownloadGif function.

⚠ Some other changes

Some other changes were made for the sake of either speed or convenience. These changes are completely opinionated and may include breaking changes that I may not be aware of, so please consider them carefully.

1. The package.json file is modified to include the package gifenc, created by Matt DesLauriers. He personally reached out to me regarding this topic and it turns out that the package includes two key functions that make the GIF rendering not only much easier, but also much faster.
   1. Naturally, the package-lock.json file also changes.
2. The Gruntfile.js is also changed. In order to include Matt's package, we needed to first compile the javascript code to babel code, before uglifying it. The uglify module wouldn't process the ES6 notation for some reason, although I've seen in some places that the project is already accounting for that. That is the babel module that appears in lines like grunt.loadNpmTasks('grunt-babel');
   1. Also, the ecmaVersion wouldn't pass the npm run build nor npm run lint nor any other command of this kind altogether. So I bumped up the version to 8 and it seems to be working fine.

Again, all these changes are considered from a rather ignorant and novel standpoint, so maybe I am making very questionable decisions here. I ask the community to pay special attention here, though it does not need to be said that I will try my best for this to be as close to perfect as it can be.

Screenshots of the change:

These are some screenshots of the tool in use. We wrote the function keyPressed and we are tracking the 's' key. When pressed, a gif will be rendered and downloaded. A beautiful sketch by @TomasMiskov is presented.

During the saving and rendering, a little paragraph appears indicating the progress. I feel like this is very important since, even though it usually only takes a couple of seconds, a couple of seconds in web time is an almost infinite amount of time.

The resulting gif is presented here, just shy over 1MB in size:

PR Checklist

• [x] npm run lint passes
• [x] Inline documentation is included / updated
• [ ] Unit tests are included / updated

[jesi-rgb]

@limzykenneth @Qianqianye don't know exactly who I have to ping for this but this is review-ready! let me know if I have to proceed further before the review or do something else. hope you have a great day :)

[jesi-rgb]

Thanks so much for the review, @davepagurek!

[Qianqianye]

Great work @jesi-rgb! Thanks @davepagurek for the review. As @jesi-rgb 's mentor @endurance21, please feel free to merge the PR when it's ready. Thank you!

[jesi-rgb]

@endurance21 Well! The example errors we talked about are fixed! To be honest, there was nothing to fix on the first place.

Either grunt or firefox or something was caching the old code and preveting the new code to be used in the example. I just removed every p5.js file under /lib and re-built again.

Unless something else can be added, I think we are ready!

[davepagurek]

Also, I notice that gifs turn out all black if I call saveGif inside setup(). I'm not sure exactly why this is happening yet, since this is all that happens between setup() and draw(). I suspect it might have something to do with the first draw is getting called after setup finishes regardless of noLoop() being called, so there could be some double-drawing? e.g. adding this to the top of saveGif fixes it:

if (this._setupDone) {
  await new Promise((res) => window.requestAnimationFrame(res));
}

That's a bit of a hack though, so in any case, I think it's also fine to add something to the documentation saying it has to be called outside of setup for now.

[jesi-rgb]

@davepagurek yes, I knew that calling within setup causes problems and wanted to make it possible for those that may unintentionally put it there to just work.

Unfortunately, the snippet of code you shared didn't work for me! I'll just state that in the documentation for now, while we manage some ways to make this work :)

[davepagurek]

Unfortunately, the snippet of code you shared didn't work for me! I'll just state that in the documentation for now, while we manage some ways to make this work :)

Sounds good! Also, that's interesting that it doesn't work, I guess there's more to it than I thought 🤔 Definitely out of scope for this PR then! If you feel like sending the sketch it doesn't work for, I can poke around in it and see if I can debug some more!

[endurance21]

@jesi-rgb great work! I have reviewed the PR and tested it locally, and happy to say that the animation to gif feature is working just fine and is in the stage to be made available to the public and thus merging now.

Disclaimer : This PR contains the one basic discussion regarding the "babel parsing the es6-es5 code and the role of uglifyJs ", which is still a matter of discussion within the group, however for now the solution provided by this pr seems reasonable to that discussion and if a better solution is discovered in near future, it shall definitely be incorporated.