Animated GIF masking

resolves #5174

When the mask method is called on an Image that contains an animated
GIF, the mask is applied to all of its frames.

Author: yifanmai

src/image/p5.Image.js

@@ -657,7 +657,32 @@ p5.Image.prototype.mask = function(p5Image) {
   ];
 
   this.drawingContext.globalCompositeOperation = 'destination-in';
-  p5.Image.prototype.copy.apply(this, copyArgs);
+  if (this.gifProperties) {
+    const prevFrameData = this.drawingContext.getImageData(
+      0,
+      0,
+      this.width,
+      this.height
+    );
+    for (let i = 0; i < this.gifProperties.frames.length; i++) {
+      this.drawingContext.clearRect(0, 0, this.width, this.height);
+      this.drawingContext.putImageData(
+        this.gifProperties.frames[i].image,
+        0,
+        0
+      );
+      p5.Image.prototype.copy.apply(this, copyArgs);
+      this.gifProperties.frames[i].image = this.drawingContext.getImageData(
+        0,
+        0,
+        this.width,
+        this.height
+      );
+    }
+    this.drawingContext.putImageData(prevFrameData, 0, 0);
+  } else {
+    p5.Image.prototype.copy.apply(this, copyArgs);
+  }
   this.drawingContext.globalCompositeOperation = currBlend;
   this.setModified(true);
 };

test/unit/image/p5.Image.js

@@ -49,4 +49,70 @@ suite('p5.Image', function() {
       assert.strictEqual(img.height, 30);
     });
   });
+
+  suite('p5.Image.prototype.mask', function() {
+    test('it should mask the image', function() {
+      let img = myp5.createImage(10, 10);
+      img.loadPixels();
+      for (let i = 0; i < img.height; i++) {
+        for (let j = 0; j < img.width; j++) {
+          let alpha = i < 5 ? 255 : 0;
+          img.set(i, j, myp5.color(0, 0, 0, alpha));
+        }
+      }
+      img.updatePixels();
+
+      let mask = myp5.createImage(10, 10);
+      mask.loadPixels();
+      for (let i = 0; i < mask.width; i++) {
+        for (let j = 0; j < mask.height; j++) {
+          let alpha = j < 5 ? 255 : 0;
+          mask.set(i, j, myp5.color(0, 0, 0, alpha));
+        }
+      }
+      mask.updatePixels();
+
+      img.mask(mask);
+      img.loadPixels();
+      for (let i = 0; i < img.width; i++) {
+        for (let j = 0; j < img.height; j++) {
+          let alpha = i < 5 && j < 5 ? 255 : 0;
+          assert.strictEqual(img.get(i, j)[3], alpha);
+        }
+      }
+    });
+
+    test('it should mask the animated gif image', function() {
+      const imagePath = 'unit/assets/nyan_cat.gif';
+      return new Promise(function(resolve, reject) {
+        myp5.loadImage(imagePath, resolve, reject);
+      }).then(function(img) {
+        let mask = myp5.createImage(img.width, img.height);
+        mask.loadPixels();
+        for (let i = 0; i < mask.width; i++) {
+          for (let j = 0; j < mask.height; j++) {
+            const alpha = j < img.height < 2 ? 255 : 0;
+            mask.set(i, j, myp5.color(0, 0, 0, alpha));
+          }
+        }
+        mask.updatePixels();
+
+        img.mask(mask);
+        for (
+          frameIndex = 0;
+          frameIndex < img.gifProperties.numFrames;
+          frameIndex++
+        ) {
+          const frameData = img.gifProperties.frames[frameIndex].image.data;
+          for (let i = 0; i < img.width; i++) {
+            for (let j = 0; j < img.height; j++) {
+              const index = 4 * (i + j * img.width) + 3;
+              const alpha = j < img.height < 2 ? 255 : 0;
+              assert.strictEqual(frameData[index], alpha);
+            }
+          }
+        }
+      });
+    });
+  });
 });