Mask documentation should mention that applying masks is destructive

[JetStarBlues]

How would this new feature help increase access to p5.js?

Undocumented behavior.

Most appropriate sub-area of p5.js?

• Accessibility (Web Accessibility)
• Build tools and processes
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Friendly error system
• Image
• IO (Input/Output)
• Localization
• Math
• Unit Testing
• Typography
• Utilities
• WebGL
• Other (documentation)

Feature enhancement details:

The documentation for p5.Image mask() fails to mention that applying a mask to an image changes the original image. I think a note mentioning this would be useful.

This behaviour might come as a surprise if for example, someone tries to apply a different mask to the same image. (Especially if they are used to the non-destructive nature of masks in photo and video editing software.)

Here is a demo of the behaviour. In the code, we first start with a yellow triangle. On mouse click, a square mask is applied to the triangle. On the next mouse click, a circle mask is applied to the triangle. On the next mouse click, the square mask is applied again, then circle again etc. The effects of each of these masks is cumulative.

[limzykenneth]

I don't quite follow how this differ from photo editing software where adding one mask on top of another does have the effect of stacking the two masks instead of just having the effect of the last applied mask?

[JetStarBlues]

@limzykenneth The difference here is that the original image itself is permanently changed. In photo editing software, the original image is never altered. This allows you to toggle a mask (or many masks) on or off. (The mask is like a layer).

Whereas when you do myImage.mask( myMask ), myImage is permanently changed. You cannot "remove" the mask. (As such if you want to keep the original image, you first have to make a copy and apply the mask to the copy).