adding clarifications

core/src/processing/core/PSurface.java

@@ -103,9 +103,21 @@ public interface PSurface {
 
   public void setSize(int width, int height);
 
+  /**
+   * Called by {@link PApplet#createGraphics(int, int)} to nitialize the
+   * {@link PGraphics#image} object with an image that's compatible with this
+   * drawing surface/display/hardware.
+   * @param gr PGraphics object whose image will be set
+   * @param wide
+   * @param high
+   */
   // create pixel buffer (pulled out for offscreen graphics)
   public void initImage(PGraphics gr, int wide, int high);
 
+  /**
+   * Sometimes smoothing must be set at the drawing surface level
+   * not just inside the renderer itself.
+   */
   public void setSmooth(int level);
 
   public void setFrameRate(float fps);

core/src/processing/core/PSurfaceAWT.java

@@ -375,7 +375,7 @@ public class PSurfaceAWT implements PSurface {
     }
     frame.getContentPane().setBackground(backgroundColor);
 
-    // Set the trimmings around the image
+    // Put the p5 logo in the Frame's corner to override the Java coffee cup.
     setIconImage(frame);
 
     // For 0149, moving this code (up to the pack() method) before init().
@@ -812,7 +812,7 @@ public class PSurfaceAWT implements PSurface {
   }
 
 
-  // get the bounds for all displays
+  /** Get the bounds rectangle for all displays. */
   static Rectangle getDisplaySpan() {
     Rectangle bounds = new Rectangle();
     GraphicsEnvironment environment =
@@ -1418,8 +1418,8 @@ public class PSurfaceAWT implements PSurface {
   // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 
 
-  int cursorType = PConstants.ARROW; // cursor type
-  boolean cursorVisible = true; // cursor visibility flag
+  int cursorType = PConstants.ARROW;
+  boolean cursorVisible = true;
   Cursor invisibleCursor;
 
 
@@ -1436,26 +1436,22 @@ public class PSurfaceAWT implements PSurface {
 
 
   public void setCursor(PImage img, int x, int y) {
-    // don't set this as cursor type, instead use cursor_type
-    // to save the last cursor used in case cursor() is called
+    // Don't set cursorType, instead use cursorType to save the last
+    // regular cursor type used for when cursor() is called.
     //cursor_type = Cursor.CUSTOM_CURSOR;
-    Image jimage =
-      canvas.getToolkit().createImage(new MemoryImageSource(img.width, img.height,
-                                        img.pixels, 0, img.width));
-    Point hotspot = new Point(x, y);
-    Toolkit tk = Toolkit.getDefaultToolkit();
-    Cursor cursor = tk.createCustomCursor(jimage, hotspot, "Custom Cursor");
+    Cursor cursor =
+      canvas.getToolkit().createCustomCursor((Image) img.getNative(),
+                                             new Point(x, y),
+                                             "custom");
     canvas.setCursor(cursor);
     cursorVisible = true;
-
   }
 
 
   public void showCursor() {
-    // maybe should always set here? seems dangerous, since
-    // it's likely that java will set the cursor to something
-    // else on its own, and the applet will be stuck b/c bagel
-    // thinks that the cursor is set to one particular thing
+    // Maybe should always set here? Seems dangerous, since it's likely that
+    // Java will set the cursor to something else on its own, and the sketch
+    // will be stuck b/c p5 thinks the cursor is set to one particular thing.
     if (!cursorVisible) {
       cursorVisible = true;
       canvas.setCursor(Cursor.getPredefinedCursor(cursorType));
@@ -1464,8 +1460,8 @@ public class PSurfaceAWT implements PSurface {
 
 
   public void hideCursor() {
-    // in 0216, just re-hide it?
-//  if (!cursorVisible) return;  // don't hide if already hidden.
+    // Because the OS may have shown the cursor on its own,
+    // don't return if 'cursorVisible' is set to true. [rev 0216]
 
     if (invisibleCursor == null) {
       BufferedImage cursorImg =
@@ -1473,9 +1469,6 @@ public class PSurfaceAWT implements PSurface {
       invisibleCursor =
         canvas.getToolkit().createCustomCursor(cursorImg, new Point(8, 8), "blank");
     }
-    // was formerly 16x16, but the 0x0 was added by jdf as a fix
-    // for macosx, which wasn't honoring the invisible cursor
-//  cursor(invisibleCursor, 8, 8);
     canvas.setCursor(invisibleCursor);
     cursorVisible = false;
   }

core/todo.txt

@@ -67,6 +67,7 @@ X   add check to require .vlw extension with loadFont()
 X Memory usage insane increasing in 3.0a5
 X   https://github.com/processing/processing/issues/3007
 X   seems fixed due to the rewrite
+X remove set/get/removeCache() methods from PApplet (add //ignore line)
 
 full screen
 X roll back full screen changes
@@ -79,11 +80,19 @@ o   sketchDisplay() -> 0 for all, or 1, 2, 3...
 X   added --span option
 X play with improvements to full screen here
 
-_ exitCalled() and exitActual made public by Andres, breaks Python
-_   also not API we want to expose, so sort this out
+_ remove setTitle() etc methods from PSurface, just use the ones from Frame?
+_   and with that, encourage the use of the dummy frame object in renderers
 _ destroy() removed, but bring back? is that better than dispose()?
 _   Python Mode has a hook for when it's called
 
+opengl misc
+_ sketchQuality() vs sketchSmooth()?
+_ move glsl entries to their own subdirectory?
+_ exitCalled() and exitActual made public by Andres, breaks Python
+_   also not API we want to expose, so sort this out
+_ get code into makeGraphics() to handle bad path settings for LWJGL
+_   right now it has a bunch of JOGL-specific code
+
 _ split 'present' and 'full screen'?
 _   --full-screen causes considerable flicker at this point
 _   or split them when sketchWidth/Height are implemented?