additional documentation changes, moved from the old faq

core/src/processing/core/PApplet.java

@@ -969,6 +969,57 @@ public class PApplet extends Applet
   }
 
 
+  /**
+   * Create an offscreen PGraphics object for drawing. This can be used
+   * for bitmap or vector images drawing or rendering.
+   *
+   * <UL>
+   * <LI>Do not use "new PGraphicsXxxx()", use this method. This method
+   * ensures that internal variables are set up properly that tie the
+   * new graphics context back to its parent PApplet.
+   * <LI>The basic way to create bitmap images is to use the <A
+   * HREF="http://processing.org/reference/saveFrame_.html">saveFrame()</A>
+   * function.
+   * <LI>If you want to create a really large scene and write that,
+   * first make sure that you've allocated a lot of memory in the Preferences.
+   * <LI>If you want to create images that are larger than the screen,
+   * you should create your own PGraphics object, draw to that, and use
+   * <A HREF="http://processing.org/reference/save_.html">save()</A>.
+   * For now, it's best to use <A HREF="http://dev.processing.org/reference/everything/javadoc/processing/core/PGraphics3D.html">P3D</A> in this scenario.
+   * P2D is currently disabled, and the JAVA2D default will give mixed
+   * results. An example of using P3D:
+   * <PRE>
+   *
+   * PGraphics big;
+   *
+   * void setup() {
+   *   big = createGraphics(3000, 3000, P3D);
+   *
+   *   big.beginDraw();
+   *   big.background(128);
+   *   big.line(20, 1800, 1800, 900);
+   *   // etc..
+   *   big.endDraw();
+   *
+   *   // make sure the file is written to the sketch folder
+   *   big.save("big.tif");
+   * }
+   *
+   * </PRE>
+   * <LI>It's important to always wrap drawing to createGraphics() with
+   * beginDraw() and endDraw() (beginFrame() and endFrame() prior to
+   * revision 0115). The reason is that the renderer needs to know when
+   * drawing has stopped, so that it can update itself internally.
+   * This also handles calling the defaults() method, for people familiar
+   * with that.
+   * <LI>It's not possible to use createGraphics() with the OPENGL renderer,
+   * because it doesn't allow offscreen use.
+   * <LI>With Processing 0115 and later, it's possible to write images in
+   * formats other than the default .tga and .tiff. The exact formats and
+   * background information can be found in the developer's reference for
+   * <A HREF="http://dev.processing.org/reference/core/javadoc/processing/core/PImage.html#save(java.lang.String)">PImage.save()</A>.
+   * </UL>
+   */
   static public PGraphics createGraphics(int iwidth, int iheight,
                                          String irenderer, String ipath,
                                          PApplet applet) {

core/src/processing/core/PGraphicsJava2D.java

@@ -31,6 +31,22 @@ import java.awt.image.*;
 /**
  * Subclass for PGraphics that implements the graphics API
  * in Java 1.3+ using Java 2D.
+ *
+ * <p>Pixel operations too slow? As of release 0085 (the first beta),
+ * the default renderer uses Java2D. It's more accurate than the renderer
+ * used in alpha releases of Processing (it handles stroke caps and joins,
+ * and has better polygon tessellation), but it's super slow for handling
+ * pixels. At least until we get a chance to get the old 2D renderer
+ * (now called P2D) working in a similar fashion, you can use
+ * <TT>size(w, h, P3D)</TT> instead of <TT>size(w, h)</TT> which will
+ * be faster for general pixel flipping madness. </p>
+ *
+ * <p>To get access to the Java 2D "Graphics2D" object for the default
+ * renderer, use:
+ * <PRE>Graphics2D g2 = ((PGraphics2)g).g2;</PRE>
+ * This will let you do Java 2D stuff directly, but is not supported in
+ * any way shape or form. Which just means "have fun, but don't complain
+ * if it breaks."</p>
  */
 public class PGraphicsJava2D extends PGraphics {
 
@@ -784,7 +800,7 @@ public class PGraphicsJava2D extends PGraphics {
                         RenderingHints.VALUE_ANTIALIAS_ON :
                         RenderingHints.VALUE_ANTIALIAS_OFF);
     */
-    
+
     Object antialias =
       g2.getRenderingHint(RenderingHints.KEY_ANTIALIASING);
 
@@ -810,7 +826,7 @@ public class PGraphicsJava2D extends PGraphics {
     // return to previous smoothing state if it was changed
     //g2.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, textAntialias);
     g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING, antialias);
-    
+
     textX = x + textWidthImpl(buffer, start, stop);
     textY = y;
     textZ = 0;  // this will get set by the caller if non-zero

todo.txt

@@ -49,6 +49,9 @@ X keep checking whether google has started to honor robots.txt
 X   http://www.google.com/search?hl=en&lr=&q=angleMode+site%3Aprocessing.org&btnG=Search
 X add load/updatePixels stuff to the pixels[] reference
 X   make mention of doing it to main pix array, and on an image
+X move fwd/back tab into the tab menu
+X   however it includes a bug that loses focus (at least on osx)
+X   http://dev.processing.org/bugs/show_bug.cgi?id=402
 
 video
 X quicktime in applets
@@ -146,18 +149,17 @@ X   on unix machines it's also possible to use a symlink
 _ need to write converter that will handle syntax changes
 _   basically find & replace with regexps
 _   framerate() -> frameRate()
-_ add info to the new faq
-_   where to find out about embedding PApplet (the dev ref)
-_   also the link to the eclipse integration
-_   also add to the platforms page
-_     i want to use java 1.5 crap (so do it, just don't use our env)
+X add info to the new faq
+X   where to find out about embedding PApplet (the dev ref)
+X   also the link to the eclipse integration
+X   also add to the platforms page
+X     i want to use java 1.5 crap (so do it, just don't use our env)
 X   where have all the old faq pages gone?
-_ add to createImage() or createGraphics reference:
-_   Creating bitmap images - from advanced.html
-_ move fwd/back tab into the tab menu
-_ add to opengl ref the information about downloading more native libs
-_   we only include linux-i586, macosx (ppc and universal), windows
-_   also can get linux amd64 and sunos, just need to include the libs
+X add to opengl ref the information about downloading more native libs
+X   we only include linux-i586, macosx (ppc and universal), windows
+X   also can get linux amd64 and sunos, just need to include the libs
+X add to createImage() or createGraphics reference:
+X   Creating bitmap images - from advanced.html
 _ the "export folder" command doesn't seem to work at all
 _   check with casey, see if he's using it
 _ on archive sketch, open the sketch folder where it's saved
@@ -551,6 +553,8 @@ _   http://dev.processing.org/bugs/show_bug.cgi?id=39
 
 PDE / Editor Header
 
+_ cmd-{ and cmd-} no longer work after the menu is shown
+_   http://dev.processing.org/bugs/show_bug.cgi?id=402
 _ make some fancy extendo things because the tabs get too big
 _   either condense or popdown menu thingy
 _   http://dev.processing.org/bugs/show_bug.cgi?id=54