Clear() Method Description Page confusing

[ptr2null]

Issue description

The description tells the reader that this method clears the pixel within a buffer. That seems not be actually correct: This method just set the background to (0,0,0,0), so fully reset the background (Source Code of PGraphics.java, current version). It does nothing else, so drawn lines or points were not erased and can still be seen.

URL(s) of affected page(s)

https://processing.org/reference/clear_.html

Proposed fix

Perhaps the authors of the description wanted to implement the written description and just have forgotten it or they forgot to update the description. Either way, it should be corrected.

[scotthmurray]

Yes, this is what PGraphis.clear() is supposed to do: “… clears everything in a PGraphics object to make all of the pixels 100% transparent.”

If you're seeing otherwise, could you post some example code to reproduce? Please clarify what you'd expect to see, and what you do see. Thanks!

[ptr2null]

Hey! Thank you for picking this up. Maybe I make a fool of me, but I really don't get the point of the concept.

Let's take the example on the reference page of the clear() method, but put the line of background() in the setup() method. Let it run in processing.

PGraphics pg;

void setup() {
  size(200, 200);
  pg = createGraphics(100, 100);
  background(204);
}

void draw() {
  pg.beginDraw();
  pg.stroke(0, 102, 153);
  pg.line(0, 0, mouseX, mouseY);
  pg.endDraw();
  image(pg, 50, 50); 
}

// Click to clear the PGraphics object
void mousePressed() {
  pg.beginDraw(); 
  pg.clear();
  pg.endDraw(); 
}

The result of the example above is that every drawn line is still seen. If I put the background(204) line in the draw method, it gets cleared. But why?

A real world example: Think of a heart-beat graph. The line is drawn from left to right on the window and should be cleared if it reaches the rightest point of the window. As a background I want to setup a grid or a coordinate system with x and y axis.

Now, if I do set the grid in the setup() method, perhaps with an initial function, the clear() method on the PGraphics object would just paint me a transparent background to zero, so black. It does not clear me the line, as I would expect it from this methods name.

This doesn't feel logical to me, as I want to setup the background just one time (whatever it is) and I would expect that the PGraphics object behaves like another layer on top of this setup. And I would also expect from the clear() method that it clears every value on a PGraphics object or a pixels-buffer within the object, as the description states.

Perhaps you can resolve my confusion.

[benfry]

The mousePressed() method is called after everything else in draw(), which means you never see the results of your clear() call.

[ptr2null]

Thank you, benfry, for joining in.

Do I understand this correctly that the clear() method just sets all pixels transparent, so that the next call of any drawing function is able to paint over the drawn pixels?

[marco-m]

@ptr2null I arrived to this ticket as confused as you, but then googling and googling and comparing code samples I finally saw the light :-)

The documentation of clear() is correct. What is confusing is not realizing completely that a PGrahics is an "an off-screen graphics buffer" and that the only way to really use it is to make it appear on the default "canvas" (don't know the Processing name) via image().

Graphically:

layer_N
...
layer_1
layer_0

where layer_0 is the "default" layer/canvas, and layer_1 ... layer_N are PGraphics objects superposed one over the other via image().

Say in draw() we call clear() for layer_1 and then superpose it on the default layer with image(). IF before calling image() we call background() on the default layer, THEN the result of the same image() call in the previous frame is erased. If on the other hand we don't call background(), AND layer_1 is transparent (which it is by default and as a result of calling clear()), then what we see is both what was in layer_1 in the previous frame and what is in layer_1 in the current frame.

I hope this answers your question "The result of the example above is that every drawn line is still seen. If I put the background(204) line in the draw() method, it gets cleared. But why?"

Every drawn line is still seen because they are not more on your PGraphics, they have been copied to the default layer/PGraphics by image().

Once you let this sink in, I think it becomes clear :-D (pun intended)

[REAS]

I modified the example in the Reference to hopefully make this more clear.