Add `beginClip()` and `endClip()` masking functions

[SableRaf]

Relevant sub-area for this feature?

Core/Environment/Rendering

Feature details

Feature description

Add beginClip() and endClip() to define clipping masks using drawing commands. Shapes drawn between these calls become the mask. An optional invert flag enables inverse masking.

Benefits

• More intuitive and less verbose than mask()
• Matches p5.js API and reduces cognitive load when switching from one to the other

Challenges

• Not sure

Additional context

See https://p5js.org/reference/p5/beginClip/

Example code

This mask() code...

  // Create pattern graphics
  pattern = createGraphics(width, height);
  pattern.beginDraw();
  pattern.background(255);
  pattern.stroke(0);
  pattern.strokeWeight(2);
  for (int x = 0; x < width; x += 10) {
    pattern.line(x, 0, x, height);
  }
  pattern.endDraw();

  // Create mask graphics (white circle on black)
  maskImg = createGraphics(width, height);
  maskImg.beginDraw();
  maskImg.background(0);
  maskImg.noStroke();
  maskImg.fill(255);
  maskImg.ellipse(width/2, height/2, 200, 200);
  maskImg.endDraw();

  // Apply mask to pattern
  pattern.mask(maskImg);

... becomes this using beginClip()/endClip():

  // Define clipping region
  beginClip();
  ellipse(width/2, height/2, 200, 200);
  endClip();

  // Draw pattern inside the clip
  stroke(0);
  strokeWeight(2);
  for (int x = 0; x < width; x += 10) {
    line(x, 0, x, height);
  }

Would you like to help implement this feature?

No, I’m just suggesting the feature

[Stefterv]

The only thing I'd like to know of the 2nd api is that if the clip would need to be applied to every draw action. In total there would be 2 + width / 10 times call to apply the mask. In a P2D context I expect this wouldn't be much of an issue, in a JAVA2D context would be quite slow. Any idea on how p5js handles that?

[SableRaf]

Any idea on how p5js handles that?

Maybe @davepagurek or @ksen0 can comment on that?

[davepagurek]

Hi! In p5 in WebGL mode, clipping is implemented via a WebGL stencil buffer that is drawn to, so under the hood the subsequent draws are compared with the bitmap stencil buffer before a given pixel is updated. In 2D mode, this is implemented via the native 2D drawing context clip() method, which does vector clipping. So under the hood, every vector that gets drawn gets booleaned with the mask before being drawn (you can also change the fill rule, EVENODD vs NONZERO, which hints at how this is implemented in the browser.)

[SableRaf]

Thanks @davepagurek!

@Stefterv: I found this about clipping in Java2D https://docs.oracle.com/javase/tutorial/2d/advanced/clipping.html