From 8a7c9571faf2248cf125d7903b97e7cf4d83040a Mon Sep 17 00:00:00 2001 From: Anadroid Date: Tue, 15 Sep 2020 10:17:15 +0200 Subject: [PATCH] Updated descriptions in comments for processing core and libraries --- core/src/processing/core/PApplet.java | 5137 +++++++++-------- core/src/processing/core/PConstants.java | 92 +- core/src/processing/core/PFont.java | 43 +- core/src/processing/core/PGraphics.java | 2370 ++++---- core/src/processing/core/PImage.java | 275 +- core/src/processing/core/PShape.java | 128 +- core/src/processing/core/PVector.java | 199 +- core/src/processing/data/FloatDict.java | 83 +- core/src/processing/data/FloatList.java | 22 +- core/src/processing/data/IntDict.java | 43 +- core/src/processing/data/IntList.java | 30 +- core/src/processing/data/JSONArray.java | 103 +- core/src/processing/data/JSONObject.java | 68 +- core/src/processing/data/StringDict.java | 14 +- core/src/processing/data/StringList.java | 14 +- core/src/processing/data/Table.java | 215 +- core/src/processing/data/TableRow.java | 24 +- core/src/processing/data/XML.java | 168 +- java/libraries/io/src/processing/io/I2C.java | 130 +- java/libraries/io/src/processing/io/LED.java | 31 +- java/libraries/io/src/processing/io/PWM.java | 39 +- java/libraries/io/src/processing/io/SPI.java | 82 +- .../io/src/processing/io/SoftwareServo.java | 65 +- .../net/src/processing/net/Client.java | 16 +- .../net/src/processing/net/Server.java | 2 +- .../serial/src/processing/serial/Serial.java | 1 - 26 files changed, 5190 insertions(+), 4204 deletions(-) diff --git a/core/src/processing/core/PApplet.java b/core/src/processing/core/PApplet.java index b7403af06..2a722fcd0 100644 --- a/core/src/processing/core/PApplet.java +++ b/core/src/processing/core/PApplet.java @@ -154,7 +154,7 @@ public class PApplet implements PConstants { * around it and not be placed in the upper corner of the screen. On Mac OS * X, the menu bar will remain present unless "Present" mode is used. * - * + * */ public int displayWidth; @@ -170,7 +170,7 @@ public class PApplet implements PConstants { * around it and not be placed in the upper corner of the screen. On Mac OS * X, the menu bar will remain present unless "Present" mode is used. * - * + * */ public int displayHeight; @@ -201,20 +201,21 @@ public class PApplet implements PConstants { /** * - * Array containing the values for all the pixels in the display window. - * These values are of the color datatype. This array is the size of the - * display window. For example, if the image is 100x100 pixels, there will - * be 10000 values and if the window is 200x300 pixels, there will be 60000 - * values. The index value defines the position of a value within - * the array. For example, the statement color b = pixels[230] will - * set the variable b to be equal to the value at that location in - * the array.
- *
- * Before accessing this array, the data must loaded with the - * loadPixels() function. After the array data has been modified, - * the updatePixels() function must be run to update the changes. - * Without loadPixels(), running the code may (or will in future - * releases) result in a NullPointerException. + * The pixels[] array contains the values for all the pixels in the + * display window. These values are of the color datatype. This array is + * defined by the size of the display window. For example, if the window is + * 100 x 100 pixels, there will be 10,000 values and if the window is + * 200 x 300 pixels, there will be 60,000 values. When the pixel density is + * set to higher than 1 with the pixelDensity() function, these values + * will change. See the reference for pixelWidth or pixelHeight + * for more information. + *

+ * Before accessing this array, the data must loaded with the loadPixels() + * function. Failure to do so may result in a NullPointerException. Subsequent + * changes to the display window will not be reflected in pixels until + * loadPixels() is called again. After pixels has been modified, + * the updatePixels() function must be run to update the content of the + * display window. * * * @webref image:pixels @@ -235,8 +236,8 @@ public class PApplet implements PConstants { * System variable which stores the width of the display window. This value * is set by the first parameter of the size() function. For * example, the function call size(320, 240) sets the width - * variable to the value 320. The value of width is zero until - * size() is called. + * variable to the value 320. The value of width defaults to 100 if + * size() is not used in a program. * * @webref environment * @webBrief System variable which stores the width of the display window. @@ -250,8 +251,8 @@ public class PApplet implements PConstants { * System variable which stores the height of the display window. This * value is set by the second parameter of the size() function. For * example, the function call size(320, 240) sets the height - * variable to the value 240. The value of height is zero until - * size() is called. + * variable to the value 240. The value of height defaults to 100 if + * size() is not used in a program. * * @webref environment * @webBrief System variable which stores the height of the display window. @@ -313,6 +314,13 @@ public class PApplet implements PConstants { * * The system variable mouseX always contains the current horizontal * coordinate of the mouse. + *

+ * Note that Processing can only track the mouse position when the pointer + * is over the current window. The default value of mouseX is 0, + * so 0 will be returned until the mouse moves in front of the sketch + * window. (This typically happens when a sketch is first run.) Once the + * mouse moves away from the window, mouseX will continue to report + * its most recent position. * * @webref input:mouse * @webBrief The system variable that always contains the current horizontal coordinate of the mouse. @@ -336,6 +344,13 @@ public class PApplet implements PConstants { * * The system variable mouseY always contains the current vertical * coordinate of the mouse. + *

+ * Note that Processing can only track the mouse position when the pointer + * is over the current window. The default value of mouseY is 0, + * so 0 will be returned until the mouse moves in front of the sketch + * window. (This typically happens when a sketch is first run.) Once the + * mouse moves away from the window, mouseY will continue to report + * its most recent position. * * @webref input:mouse * @webBrief The system variable that always contains the current vertical coordinate of the mouse. @@ -359,21 +374,21 @@ public class PApplet implements PConstants { * The system variable pmouseX always contains the horizontal * position of the mouse in the frame previous to the current frame.
*
- * You may find that pmouseX and pmouseY have different - * values inside draw() and inside events like mousePressed() - * and mouseMoved(). This is because they're used for different - * roles, so don't mix them. Inside draw(), pmouseX and - * pmouseY update only once per frame (once per trip through your - * draw()). But, inside mouse events, they update each time the - * event is called. If they weren't separated, then the mouse would be read - * only once per frame, making response choppy. If the mouse variables were - * always updated multiple times per frame, using line(pmouseX, - * pmouseY, mouseX, mouseY) inside draw() would have lots - * of gaps, because pmouseX may have changed several times in - * between the calls to line(). Use pmouseX and - * pmouseY inside draw() if you want values relative to the - * previous frame. Use pmouseX and pmouseY inside the mouse - * functions if you want continuous response. + * You may find that pmouseX and pmouseY have different values + * when referenced inside of draw() and inside of mouse events like + * mousePressed() and mouseMoved(). Inside draw(), + * pmouseX and pmouseY update only once per frame (once per trip + * through the draw() loop). But inside mouse events, they update each + * time the event is called. If these values weren't updated immediately during + * events, then the mouse position would be read only once per frame, resulting + * in slight delays and choppy interaction. If the mouse variables were always + * updated multiple times per frame, then something like line(pmouseX, pmouseY, + * mouseX, mouseY) inside draw() would have lots of gaps, because + * pmouseX may have changed several times in between the calls to + * line().

+ * If you want values relative to the previous frame, use pmouseX and + * pmouseY inside draw(). If you want continuous response, use + * pmouseX and pmouseY inside the mouse event functions. * * @webref input:mouse * @webBrief The system variable that always contains the horizontal @@ -448,10 +463,13 @@ public class PApplet implements PConstants { /** * - * Processing automatically tracks if the mouse button is pressed and which - * button is pressed. The value of the system variable mouseButton - * is either LEFT, RIGHT, or CENTER depending on which - * button is pressed. + * When a mouse button is pressed, the value of the system variable + * mouseButton is set to either LEFT, RIGHT, or + * CENTER, depending on which button is pressed. (If no button is + * pressed, mouseButton may be reset to 0. For that reason, + * it's best to use mousePressed first to test if any button is being + * pressed, and only then test the value of mouseButton, as shown in + * the examples above.) * * *

Advanced:

@@ -476,10 +494,15 @@ public class PApplet implements PConstants { /** * - * Variable storing if a mouse button is pressed. The value of the system - * variable mousePressed is true if a mouse button is pressed and - * false if a button is not pressed. - * + * The mousePressed() function is called once after every time a + * mouse button is pressed. The mouseButton variable (see the + * related reference entry) can be used to determine which button has + * been pressed. + *

+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops + * listening for events. + * * @webref input:mouse * @webBrief Variable storing if a mouse button is pressed. * @see PApplet#mouseX @@ -522,7 +545,10 @@ public class PApplet implements PConstants { * commonly used on PCs and Unix and the RETURN key is used instead on * Macintosh. Check for both ENTER and RETURN to make sure your program * will work for all platforms. - * + *

+ * There are issues with how keyCode behaves across different + * renderers and operating systems. Watch out for unexpected behavior as + * you switch renderers and operating systems. * *

Advanced

* @@ -544,23 +570,33 @@ public class PApplet implements PConstants { /** * * The variable keyCode is used to detect special keys such as the - * UP, DOWN, LEFT, RIGHT arrow keys and ALT, CONTROL, SHIFT. When checking - * for these keys, it's first necessary to check and see if the key is - * coded. This is done with the conditional "if (key == CODED)" as shown in - * the example. + * UP, DOWN, LEFT, RIGHT arrow keys and ALT, CONTROL, SHIFT. + *

+ * When checking for these keys, it can be useful to first check if the key + * is coded. This is done with the conditional if (key == CODED), as + * shown in the example above. *

* The keys included in the ASCII specification (BACKSPACE, TAB, ENTER, - * RETURN, ESC, and DELETE) do not require checking to see if they key is - * coded, and you should simply use the key variable instead of - * keyCode If you're making cross-platform projects, note that the - * ENTER key is commonly used on PCs and Unix and the RETURN key is used - * instead on Macintosh. Check for both ENTER and RETURN to make sure your - * program will work for all platforms. + * RETURN, ESC, and DELETE) do not require checking to see if the key is + * coded; for those keys, you should simply use the key variable + * directly (and not keyCode). If you're making cross-platform + * projects, note that the ENTER key is commonly used on PCs and Unix, + * while the RETURN key is used on Macs. Make sure your program will work + * on all platforms by checking for both ENTER and RETURN. *

- * For users familiar with Java, the values for UP and DOWN are simply - * shorter versions of Java's KeyEvent.VK_UP and KeyEvent.VK_DOWN. Other - * keyCode values can be found in the Java KeyEvent reference. + * For those familiar with Java, the values for UP and DOWN are simply + * shorter versions of Java's KeyEvent.VK_UP and KeyEvent.VK_DOWN. + * Other keyCode values can be found in the Java + * KeyEvent + * reference. + *

+ * There are issues with how keyCode behaves across different renderers + * and operating systems. Watch out for unexpected behavior as you switch + * renderers and operating systems and you are using keys are aren't mentioned + * in this reference entry. + *

+ * If you are using P2D or P3D as your renderer, use the + * NEWT KeyEvent constants. * * *

Advanced

@@ -583,6 +619,9 @@ public class PApplet implements PConstants { * * The boolean system variable keyPressed is true if any key * is pressed and false if no keys are pressed. + *

+ * Note that there is a similarly named function called keyPressed(). + * See its reference page for more information. * * @webref input:keyboard * @webBrief The boolean system variable that is true if any key @@ -606,9 +645,7 @@ public class PApplet implements PConstants { * * Confirms if a Processing program is "focused", meaning that it is active * and will accept input from mouse or keyboard. This variable is "true" if - * it is focused and "false" if not. This variable is often used when you - * want to warn people they need to click on or roll over an applet before - * it will work. + * it is focused and "false" if not. * * @webref environment * @webBrief Confirms if a Processing program is "focused". @@ -661,7 +698,7 @@ public class PApplet implements PConstants { * * @webref environment * @webBrief The system variable that contains the number of frames - * displayed since the program started. + * displayed since the program started. * @see PApplet#frameRate(float) * @see PApplet#frameRate */ @@ -887,25 +924,25 @@ public class PApplet implements PConstants { /** * - * The settings() function is new with Processing 3.0. - * It's not needed in most sketches. It's only useful when it's - * absolutely necessary to define the parameters to size() - * with a variable. Alternately, the settings() function - * is necessary when using Processing code outside of the - * Processing Development Environment (PDE). For example, when - * using the Eclipse code editor, it's necessary to use - * settings() to define the size() and + * The settings() function is new with Processing 3.0. + * It's not needed in most sketches. It's only useful when it's + * absolutely necessary to define the parameters to size() + * with a variable. Alternately, the settings() function + * is necessary when using Processing code outside of the + * Processing Development Environment (PDE). For example, when + * using the Eclipse code editor, it's necessary to use + * settings() to define the size() and * smooth() values for a sketch.. *

- * The settings() method runs before the sketch has been - * set up, so other Processing functions cannot be used at that - * point. For instance, do not use loadImage() inside settings(). - * The settings() method runs "passively" to set a few variables, - * compared to the setup() command that call commands in - * the Processing API. + * The settings() method runs before the sketch has been + * set up, so other Processing functions cannot be used at that + * point. For instance, do not use loadImage() inside settings(). + * The settings() method runs "passively" to set a few variables, + * compared to the setup() command that call commands in + * the Processing API. * * @webref environment - * @webBrief Used when absolutely necessary to define the parameters to size() + * @webBrief Used when absolutely necessary to define the parameters to size() * with a variable. * @see PApplet#fullScreen() * @see PApplet#setup() @@ -979,7 +1016,7 @@ public class PApplet implements PConstants { * and a "1" if not. This information is useful for a program to adapt to * run at double the pixel density on a screen that supports it. * - * + * * @webref environment * @webBrief Returns "2" if the screen is high-density and "1" if not. * @see PApplet#pixelDensity(int) @@ -1034,31 +1071,31 @@ public class PApplet implements PConstants { /** - * This function is new with Processing 3.0. It makes it - * possible for Processing to render using all of the - * pixels on high resolutions screens like Apple Retina - * displays and Windows High-DPI displays. This function - * can only be run once within a program and it must be - * used right after size() in a program without a setup() - * and used within setup() when a program has one. The - * pixelDensity() should only be used with hardcoded - * numbers (in almost all cases this number will be 2) - * or in combination with displayDensity() as in the + * This function is new with Processing 3.0. It makes it + * possible for Processing to render using all of the + * pixels on high resolutions screens like Apple Retina + * displays and Windows High-DPI displays. This function + * can only be run once within a program and it must be + * used right after size() in a program without a setup() + * and used within setup() when a program has one. The + * pixelDensity() should only be used with hardcoded + * numbers (in almost all cases this number will be 2) + * or in combination with displayDensity() as in the * third example above. * - * When the pixel density is set to more than 1, it - * changes all of the pixel operations including the way - * get(), set(), blend(), copy(), and updatePixels() - * all work. See the reference for pixelWidth and + * When the pixel density is set to more than 1, it + * changes all of the pixel operations including the way + * get(), set(), blend(), copy(), and updatePixels() + * all work. See the reference for pixelWidth and * pixelHeight for more information. * - * To use variables as the arguments to pixelDensity() - * function, place the pixelDensity() function within - * the settings() function. There is more information + * To use variables as the arguments to pixelDensity() + * function, place the pixelDensity() function within + * the settings() function. There is more information * about this on the settings() reference page. - * + * * @webref environment - * @webBrief It makes it possible for Processing to render using all of the + * @webBrief It makes it possible for Processing to render using all of the * pixels on high resolutions screens * @param density 1 or 2 * @see PApplet#pixelWidth @@ -1112,39 +1149,39 @@ public class PApplet implements PConstants { } /** - * Draws all geometry with smooth (anti-aliased) edges. - * This behavior is the default, so smooth() only needs - * to be used when a program needs to set the smoothing - * in a different way. The level parameter increases - * the amount of smoothness. This is the level of over + * Draws all geometry with smooth (anti-aliased) edges. + * This behavior is the default, so smooth() only needs + * to be used when a program needs to set the smoothing + * in a different way. The level parameter increases + * the amount of smoothness. This is the level of over * sampling applied to the graphics buffer. * - * With the P2D and P3D renderers, smooth(2) is the - * default, this is called "2x anti-aliasing." The code - * smooth(4) is used for 4x anti-aliasing and smooth(8) - * is specified for "8x anti-aliasing." The maximum - * anti-aliasing level is determined by the hardware of - * the machine that is running the software, so smooth(4) + * With the P2D and P3D renderers, smooth(2) is the + * default, this is called "2x anti-aliasing." The code + * smooth(4) is used for 4x anti-aliasing and smooth(8) + * is specified for "8x anti-aliasing." The maximum + * anti-aliasing level is determined by the hardware of + * the machine that is running the software, so smooth(4) * and smooth(8) will not work with every computer. - * - * The default renderer uses smooth(3) by default. This - * is bicubic smoothing. The other option for the default + * + * The default renderer uses smooth(3) by default. This + * is bicubic smoothing. The other option for the default * renderer is smooth(2), which is bilinear smoothing. * - * With Processing 3.0, smooth() is different than before. - * It was common to use smooth() and noSmooth() to turn on - * and off antialiasing within a sketch. Now, because of - * how the software has changed, smooth() can only be set - * once within a sketch. It can be used either at the top - * of a sketch without a setup(), or after the size() - * function when used in a sketch with setup(). The + * With Processing 3.0, smooth() is different than before. + * It was common to use smooth() and noSmooth() to turn on + * and off antialiasing within a sketch. Now, because of + * how the software has changed, smooth() can only be set + * once within a sketch. It can be used either at the top + * of a sketch without a setup(), or after the size() + * function when used in a sketch with setup(). The * noSmooth() function also follows the same rules. * - * When smooth() is used with a PGraphics object, it should - * be run right after the object is created with - * createGraphics(), as shown in the Reference in the third + * When smooth() is used with a PGraphics object, it should + * be run right after the object is created with + * createGraphics(), as shown in the Reference in the third * example. - * + * * @webref environment * @webBrief Draws all geometry with smooth (anti-aliased) edges. * @param level either 2, 3, 4, or 8 depending on the renderer @@ -1159,19 +1196,20 @@ public class PApplet implements PConstants { } /** - * Draws all geometry and fonts with jagged (aliased) - * edges and images with hard edges between the pixels - * when enlarged rather than interpolating pixels. Note - * that smooth() is active by default, so it is necessary - * to call noSmooth() to disable smoothing of geometry, - * fonts, and images. Since the release of Processing 3.0, - * the noSmooth() function can only be run once for each - * sketch, either at the top of a sketch without a setup(), - * or after the size() function when used in a sketch with + * Draws all geometry and fonts with jagged (aliased) + * edges and images with hard edges between the pixels + * when enlarged rather than interpolating pixels. Note + * that smooth() is active by default, so it is necessary + * to call noSmooth() to disable smoothing of geometry, + * fonts, and images. Since the release of Processing 3.0, + * the noSmooth() function can only be run once for each + * sketch, either at the top of a sketch without a setup(), + * or after the size() function when used in a sketch with * setup(). See the examples above for both scenarios. + * * @webref environment - * @webBrief Draws all geometry and fonts with jagged (aliased) - * edges and images with hard edges between the pixels + * @webBrief Draws all geometry and fonts with jagged (aliased) + * edges and images with hard edges between the pixels * when enlarged rather than interpolating pixels. */ public void noSmooth() { @@ -1677,18 +1715,20 @@ public class PApplet implements PConstants { /** * - * The setup() function is called once when the program starts. It's - * used to define initial - * enviroment properties such as screen size and background color and to - * load media such as images - * and fonts as the program starts. There can only be one setup() - * function for each program and - * it shouldn't be called again after its initial execution. Note: - * Variables declared within - * setup() are not accessible within other functions, including - * draw(). + * The setup() function is run once, when the program starts. It's used + * to define initial enviroment properties such as screen size and to load media + * such as images and fonts as the program starts. There can only be one + * setup() function for each program and it shouldn't be called again + * after its initial execution.
+ *
+ * If the sketch is a different dimension than the default, the size() + * function or fullScreen() function must be the first line in + * setup().
+ *
+ * Note: Variables declared within setup() are not accessible within + * other functions, including draw(). + * * - * * @webref structure * @webBrief The setup() function is called once when the program starts. * @usage web_application @@ -1702,21 +1742,31 @@ public class PApplet implements PConstants { /** * - * Called directly after setup() and continuously executes the lines - * of code contained inside its block until the program is stopped or - * noLoop() is called. The draw() function is called - * automatically and should never be called explicitly. It should always be - * controlled with noLoop(), redraw() and loop(). - * After noLoop() stops the code in draw() from executing, - * redraw() causes the code inside draw() to execute once and - * loop() will causes the code inside draw() to execute - * continuously again. The number of times draw() executes in each - * second may be controlled with frameRate() function. - * There can only be one draw() function for each sketch - * and draw() must exist if you want the code to run continuously or - * to process events such as mousePressed(). Sometimes, you might - * have an empty call to draw() in your program as shown in the - * above example. + * Called directly after setup(), the draw() function continuously + * executes the lines of code contained inside its block until the program is + * stopped or noLoop() is called. draw() is called automatically + * and should never be called explicitly. All Processing programs update the + * screen at the end of draw(), never earlier.
+ *
+ * To stop the code inside of draw() from running continuously, use + * noLoop(), redraw() and loop(). If noLoop() is + * used to stop the code in draw() from running, then redraw() + * will cause the code inside draw() to run a single time, and + * loop() will cause the code inside draw() to resume running + * continuously.
+ *
+ * The number of times draw() executes in each second may be controlled + * with the frameRate() function.
+ *
+ * It is common to call background() near the beginning of the + * draw() loop to clear the contents of the window, as shown in the first + * example above. Since pixels drawn to the window are cumulative, omitting + * background() may result in unintended results.
+ *
+ * There can only be one draw() function for each sketch, and draw() + * must exist if you want the code to run continuously, or to process events such + * as mousePressed(). Sometimes, you might have an empty call to + * draw() in your program, as shown in the second example above. * * @webref structure * @webBrief Called directly after setup() and continuously executes the lines @@ -1776,23 +1826,22 @@ public class PApplet implements PConstants { /** - * This function is new for Processing 3.0. It opens a - * sketch using the full size of the computer's display. - * This function must be the first line in setup(). The - * size() and fullScreen() functions cannot both be used - * in the same program, just choose one. - * When fullScreen() is used without a parameter, it draws - * the sketch to the screen currently selected inside the - * Preferences window. When it is used with a single - * parameter, this number defines the screen to display to - * program on (e.g. 1, 2, 3...). When used with two - * parameters, the first defines the renderer to use - * (e.g. P2D) and the second defines the screen. The SPAN - * parameter can be used in place of a screen number to - * draw the sketch as a full-screen window across all of - * the attached displays if there are more than one. - * Prior to Processing 3.0, a full-screen program was - * defined with size(displayWidth, displayHeight). + * This function is new for Processing 3.0. It opens a sketch using the full + * size of the computer's display. This function must be the first line in + * setup(). The size() and fullScreen() functions cannot + * both be used in the same program, just choose one.
+ *
+ * When fullScreen() is used without a parameter, it draws the sketch + * to the screen currently selected inside the Preferences window. When it is + * used with a single parameter, this number defines the screen to display to + * program on (e.g. 1, 2, 3...). When used with two parameters, the first + * defines the renderer to use (e.g. P2D) and the second defines the screen. + * The SPAN parameter can be used in place of a screen number to draw + * the sketch as a full-screen window across all of the attached displays if + * there are more than one.
+ *
+ * Prior to Processing 3.0, a full-screen program was defined with + * size(displayWidth, displayHeight). * * @webref environment * @webBrief Opens a sketch using the full size of the computer's display. @@ -1832,73 +1881,82 @@ public class PApplet implements PConstants { /** * - * Defines the dimension of the display window in units of pixels. The - * size() function must be the first line in setup(). If - * size() is not used, the default size of the window is 100x100 - * pixels. The system variables width and height are set by - * the parameters passed to this function.
+ * Defines the dimension of the display window width and height in units of + * pixels. In a program that has the setup() function, the + * size() function must be the first line of code inside + * setup(), and the setup() function must appear in the code tab + * with the same name as your sketch folder.
*
- * Do not use variables as the parameters to size() function, - * because it will cause problems when exporting your sketch. When - * variables are used, the dimensions of your sketch cannot be determined - * during export. Instead, employ numeric values in the size() - * statement, and then use the built-in width and height - * variables inside your program when the dimensions of the display window - * are needed.
+ * The built-in variables width and height are set by the + * parameters passed to this function. For example, running size(640, + * 480) will assign 640 to the width variable and 480 to the height + * variable. If size() is not used, the window will be given a + * default size of 100 x 100 pixels.
*
- * The size() function can only be used once inside a sketch, and - * cannot be used for resizing.
- *
renderer parameter selects which rendering engine to use. - * For example, if you will be drawing 3D shapes, use P3D, if you - * want to export images from a program as a PDF file use PDF. A - * brief description of the three primary renderers follows:
+ * The size() function can only be used once inside a sketch, and it + * cannot be used for resizing.
*
- * P2D (Processing 2D) - The default renderer that supports two - * dimensional drawing.
- *
- * P3D (Processing 3D) - 3D graphics renderer that makes use of - * OpenGL-compatible graphics hardware.
- *
- * PDF - The PDF renderer draws 2D graphics directly to an Acrobat - * PDF file. This produces excellent results when you need vector shapes - * for high resolution output or printing. You must first use Import - * Library → PDF to make use of the library. More information can be - * found in the PDF library reference.
- *
- * The P3D renderer doesn't support strokeCap() or - * strokeJoin(), which can lead to ugly results when using - * strokeWeight(). (Issue - * 123)
+ * As of Processing 3, to run a sketch at the full dimensions of a screen, use + * the fullScreen() function, rather than the older way of using + * size(displayWidth, displayHeight).
*
* The maximum width and height is limited by your operating system, and is - * usually the width and height of your actual screen. On some machines it - * may simply be the number of pixels on your current screen, meaning that - * a screen of 800x600 could support size(1600, 300), since it's the - * same number of pixels. This varies widely so you'll have to try - * different rendering modes and sizes until you get what you're looking - * for. If you need something larger, use createGraphics to create a - * non-visible drawing surface.
+ * usually the width and height of your actual screen. On some machines it may + * simply be the number of pixels on your current screen, meaning that a + * screen of 800 x 600 could support size(1600, 300), since that is the + * same number of pixels. This varies widely, so you'll have to try different + * rendering modes and sizes until you get what you're looking for. If you + * need something larger, use createGraphics to create a non-visible + * drawing surface.
+ *
+ * The minimum width and height is around 100 pixels in each direction. This + * is the smallest that is supported across Windows, macOS, and Linux. We + * enforce the minimum size so that sketches will run identically on different + * machines.
+ * The renderer parameter selects which rendering engine to use. For + * example, if you will be drawing 3D shapes, use P3D. In addition to + * the default renderer, other renderers are:
+ *
+ * P2D (Processing 2D): 2D graphics renderer that makes use of + * OpenGL-compatible graphics hardware.
+ *
+ * P3D (Processing 3D): 3D graphics renderer that makes use of + * OpenGL-compatible graphics hardware.
+ *
+ * FX2D (JavaFX 2D): A 2D renderer that uses JavaFX, which may be + * faster for some applications, but has some compatibility quirks.
+ * PDF: The PDF renderer draws 2D graphics directly to an Acrobat PDF + * file. This produces excellent results when you need vector shapes for + * high-resolution output or printing. You must first use Import Library + * → PDF to make use of the library. More information can be found in the + * PDF library reference.
+ *
+ * SVG: The SVG renderer draws 2D graphics directly to an SVG file. + * This is great for importing into other vector programs or using for digital + * fabrication. You must first use Import Library → SVG Export to make + * use of the library.
+ *
+ * As of Processing 3.0, to use variables as the parameters to size() + * function, place the size() function within the settings() + * function (instead of setup()). There is more information about this + * on the settings() reference page.
*
- * Again, the size() function must be the first line of the code (or - * first item inside setup). Any code that appears before the size() - * command may run more than once, which can lead to confusing results. * - * - *

Advanced

- * If using Java 1.3 or later, this will default to using - * PGraphics2, the Java2D-based renderer. If using Java 1.1, - * or if PGraphics2 is not available, then PGraphics will be used. - * To set your own renderer, use the other version of the size() - * method that takes a renderer as its last parameter. + *

Advanced

If using Java 1.3 or later, this will default to using + * PGraphics2, the Java2D-based renderer. If using Java 1.1, or if PGraphics2 + * is not available, then PGraphics will be used. To set your own renderer, + * use the other version of the size() method that takes a renderer as its + * last parameter. *

- * If called once a renderer has already been set, this will - * use the previous renderer and simply resize it. + * If called once a renderer has already been set, this will use the previous + * renderer and simply resize it. * * @webref environment * @webBrief Defines the dimension of the display window in units of pixels. - * @param width width of the display window in units of pixels - * @param height height of the display window in units of pixels + * @param width + * width of the display window in units of pixels + * @param height + * height of the display window in units of pixels * @see PApplet#width * @see PApplet#height * @see PApplet#setup() @@ -2028,40 +2086,56 @@ public class PApplet implements PConstants { /** * - * Creates and returns a new PGraphics object of the types P2D or - * P3D. Use this class if you need to draw into an off-screen graphics - * buffer. The PDF renderer requires the filename parameter. The DXF - * renderer should not be used with createGraphics(), it's only - * built for use with beginRaw() and endRaw().
+ * Creates and returns a new PGraphics object. Use this class if you + * need to draw into an off-screen graphics buffer. The first two parameters + * define the width and height in pixels. The third, optional parameter + * specifies the renderer. It can be defined as P2D, P3D, PDF, or SVG. If the + * third parameter isn't used, the default renderer is set. The PDF and SVG + * renderers require the filename parameter.
*
- * It's important to call any drawing functions between beginDraw() - * and endDraw() statements. This is also true for any functions - * that affect drawing, such as smooth() or colorMode().
- *
the main drawing surface which is completely opaque, surfaces - * created with createGraphics() can have transparency. This makes - * it possible to draw into a graphics and maintain the alpha channel. By - * using save() to write a PNG or TGA file, the transparency of the - * graphics object will be honored. Note that transparency levels are - * binary: pixels are either complete opaque or transparent. For the time - * being, this means that text characters will be opaque blocks. This will - * be fixed in a future release (Issue 80). + * It's important to consider the renderer used with createGraphics() + * in relation to the main renderer specified in size(). For example, + * it's only possible to use P2D or P3D with createGraphics() when one + * of them is defined in size(). Unlike Processing 1.0, P2D and P3D use + * OpenGL for drawing, and when using an OpenGL renderer it's necessary for + * the main drawing surface to be OpenGL-based. If P2D or P3D are used as the + * renderer in size(), then any of the options can be used with + * createGraphics(). If the default renderer is used in size(), + * then only the default, PDF, or SVG can be used with + * createGraphics().
+ *
+ * It's important to run all drawing functions between the beginDraw() + * and endDraw(). As the exception to this rule, smooth() should + * be run on the PGraphics object before beginDraw(). See the reference + * for smooth() for more detail.
+ *
+ * The createGraphics() function should almost never be used inside + * draw() because of the memory and time needed to set up the graphics. + * One-time or occasional use during draw() might be acceptable, but + * code that calls createGraphics() at 60 frames per second might run + * out of memory or freeze your sketch.
+ *
+ * Unlike the main drawing surface which is completely opaque, surfaces + * created with createGraphics() can have transparency. This makes it + * possible to draw into a graphics and maintain the alpha channel. By using + * save() to write a PNG or TGA file, the transparency of the graphics + * object will be honored. * - *

Advanced

- * Create an offscreen PGraphics object for drawing. This can be used - * for bitmap or vector images drawing or rendering. + *

Advanced

Create an offscreen PGraphics object for drawing. This + * can be used for bitmap or vector images drawing or rendering. * * * @webref rendering - * @webBrief Creates and returns a new PGraphics object of the types P2D or P3D. - * @param w width in pixels - * @param h height in pixels - * @param renderer Either P2D, P3D, or PDF + * @webBrief Creates and returns a new PGraphics object of the types + * P2D or P3D. + * @param w + * width in pixels + * @param h + * height in pixels + * @param renderer + * Either P2D, P3D, or PDF * @see PGraphics#PGraphics * */ @@ -2256,7 +2335,7 @@ public class PApplet implements PConstants { * Advanced users please note that createImage() should be used instead of * the syntax new PImage(). * - * + * *

Advanced

* Preferred method of creating new PImage objects, ensures that a * reference to the parent PApplet is included, which makes save() work @@ -2423,18 +2502,21 @@ public class PApplet implements PConstants { /** - * - * Executes the code within draw() one time. This functions allows - * the program to update the display window only when necessary, for - * example when an event registered by mousePressed() or - * keyPressed() occurs. - *

structuring a program, it only makes sense to call redraw() - * within events such as mousePressed(). This is because - * redraw() does not run draw() immediately (it only sets a - * flag that indicates an update is needed). - *

redraw() within draw() has no effect because - * draw() is continuously called anyway. - * + * + * Executes the code within draw() one time. This functions allows the + * program to update the display window only when necessary, for example when an + * event registered by mousePressed() or keyPressed() occurs. + *
+ *
+ * In structuring a program, it only makes sense to call redraw() within events + * such as mousePressed(). This is because redraw() does not run + * draw() immediately (it only sets a flag that indicates an update is + * needed).
+ *
+ * The redraw() function does not work properly when called inside + * draw(). To enable/disable animations, use loop() and + * noLoop(). + * * @webref structure * @webBrief Executes the code within draw() one time. * @usage web_application @@ -2461,12 +2543,15 @@ public class PApplet implements PConstants { } /** - * - * Causes Processing to continuously execute the code within draw(). - * If noLoop() is called, the code in draw() stops executing. - * + * + * By default, Processing loops through draw() continuously, executing + * the code within it. However, the draw() loop may be stopped by calling + * noLoop(). In that case, the draw() loop can be resumed with + * loop(). + * * @webref structure - * @webBrief Causes Processing to continuously execute the code within draw(). + * @webBrief Causes Processing to continuously execute the code within + * draw(). * @usage web_application * @see PApplet#noLoop() * @see PApplet#redraw() @@ -2498,7 +2583,7 @@ public class PApplet implements PConstants { * Otherwise, the sketch would enter an odd state until loop() was called. * * @webref structure - * @webBrief Stops Processing from continuously executing the code within draw(). + * @webBrief Stops Processing from continuously executing the code within draw(). * @usage web_application * @see PApplet#loop() * @see PApplet#redraw() @@ -2680,19 +2765,22 @@ public class PApplet implements PConstants { /** * - * The mousePressed() function is called once after every time a - * mouse button is pressed. The mouseButton variable (see the - * related reference entry) can be used to determine which button has been pressed. + * The mousePressed() function is called once after every time a mouse + * button is pressed. The mouseButton variable (see the related + * reference entry) can be used to determine which button has been pressed. + *
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events. * - * *

Advanced

* - * If you must, use - * int button = mouseEvent.getButton(); - * to figure out which button was clicked. It will be one of: - * MouseEvent.BUTTON1, MouseEvent.BUTTON2, MouseEvent.BUTTON3 - * Note, however, that this is completely inconsistent across - * platforms. + * If you must, use int button = mouseEvent.getButton(); to figure out which + * button was clicked. It will be one of: MouseEvent.BUTTON1, + * MouseEvent.BUTTON2, MouseEvent.BUTTON3 Note, however, that this is + * completely inconsistent across platforms. + * * @webref input:mouse * @webBrief Called once after every time a mouse button is pressed. * @see PApplet#mouseX @@ -2717,8 +2805,12 @@ public class PApplet implements PConstants { /** * - * The mouseReleased() function is called every time a mouse button - * is released. + * The mouseReleased() function is called every time a mouse button is + * released.
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events. * * @webref input:mouse * @webBrief Called every time a mouse button is released. @@ -2744,15 +2836,20 @@ public class PApplet implements PConstants { /** * - * The mouseClicked() function is called once after a mouse button - * has been pressed and then released. + * The mouseClicked() function is called after a mouse button + * has been pressed and then released.
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events. + * + *

Advanced

When the mouse is clicked, mousePressed() will be called, + * then mouseReleased(), then mouseClicked(). Note that mousePressed is + * already false inside of mouseClicked(). * - *

Advanced

- * When the mouse is clicked, mousePressed() will be called, - * then mouseReleased(), then mouseClicked(). Note that - * mousePressed is already false inside of mouseClicked(). * @webref input:mouse - * @webBrief Called once after a mouse button has been pressed and then released. + * @webBrief Called once after a mouse button has been pressed and then + * released. * @see PApplet#mouseX * @see PApplet#mouseY * @see PApplet#pmouseX @@ -2776,10 +2873,16 @@ public class PApplet implements PConstants { /** * * The mouseDragged() function is called once every time the mouse - * moves and a mouse button is pressed. + * moves while a mouse button is pressed. (If a button is not being + * pressed, mouseMoved() is called instead.)
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events. * * @webref input:mouse - * @webBrief Called once every time the mouse moves and a mouse button is pressed. + * @webBrief Called once every time the mouse moves and a mouse button is + * pressed. * @see PApplet#mouseX * @see PApplet#mouseY * @see PApplet#pmouseX @@ -2802,12 +2905,18 @@ public class PApplet implements PConstants { /** * - * The mouseMoved() function is called every time the mouse moves - * and a mouse button is not pressed. + * The mouseMoved() function is called every time the mouse moves and a + * mouse button is not pressed. (If a button is being pressed, + * mouseDragged() is called instead.)
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events. + * * - * * @webref input:mouse - * @webBrief Called every time the mouse moves and a mouse button is not pressed. + * @webBrief Called every time the mouse moves and a mouse button is not + * pressed. * @see PApplet#mouseX * @see PApplet#mouseY * @see PApplet#pmouseX @@ -2849,22 +2958,22 @@ public class PApplet implements PConstants { public void mouseWheel() { } /** - * The code within the mouseWheel() event function - * is run when the mouse wheel is moved. (Some mice don't - * have wheels and this function is only applicable with - * mice that have a wheel.) The getCount() function - * used within mouseWheel() returns positive values - * when the mouse wheel is rotated down (toward the user), - * and negative values for the other direction (up or away - * from the user). On OS X with "natural" scrolling enabled, + * The code within the mouseWheel() event function + * is run when the mouse wheel is moved. (Some mice don't + * have wheels and this function is only applicable with + * mice that have a wheel.) The getCount() function + * used within mouseWheel() returns positive values + * when the mouse wheel is rotated down (toward the user), + * and negative values for the other direction (up or away + * from the user). On OS X with "natural" scrolling enabled, * the values are opposite. *

- * Mouse and keyboard events only work when a program has - * draw(). Without draw(), the code is only + * Mouse and keyboard events only work when a program has + * draw(). Without draw(), the code is only * run once and then stops listening for events. * * @webref input:mouse - * @webBrief The code within the mouseWheel() event function + * @webBrief The code within the mouseWheel() event function * is run when the mouse wheel is moved. * @param event the MouseEvent * @see PApplet#mouseX @@ -2953,31 +3062,44 @@ public class PApplet implements PConstants { * * The keyPressed() function is called once every time a key is * pressed. The key that was pressed is stored in the key variable. - *

- * For non-ASCII keys, use the keyCode variable. The keys included - * in the ASCII specification (BACKSPACE, TAB, ENTER, RETURN, ESC, and - * DELETE) do not require checking to see if they key is coded, and you - * should simply use the key variable instead of keyCode If - * you're making cross-platform projects, note that the ENTER key is - * commonly used on PCs and Unix and the RETURN key is used instead on - * Macintosh. Check for both ENTER and RETURN to make sure your program - * will work for all platforms. - *

- * Because of how operating systems handle key repeats, holding down a key - * may cause multiple calls to keyPressed() (and keyReleased() as well). - * The rate of repeat is set by the operating system and how each computer - * is configured. + *
+ *
+ * For non-ASCII keys, use the keyCode variable. The keys included in + * the ASCII specification (BACKSPACE, TAB, ENTER, RETURN, ESC, and DELETE) do + * not require checking to see if the key is coded; for those keys, you should + * simply use the key variable directly (and not keyCode). If + * you're making cross-platform projects, note that the ENTER key is commonly + * used on PCs and Unix, while the RETURN key is used on Macs. Make sure your + * program will work on all platforms by checking for both ENTER and RETURN. + *
+ *
+ * Because of how operating systems handle key repeats, holding down a key may + * cause multiple calls to keyPressed(). The rate of repeat is set by + * the operating system, and may be configured differently on each computer. + *
+ *
+ * Note that there is a similarly named boolean variable called + * keyPressed. See its reference page for more information.
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events.
+ *
+ * With the release of macOS Sierra, Apple changed how key repeat works, so + * keyPressed may not function as expected. See here + * for details of the problem and how to fix it. * *

Advanced

* - * Called each time a single key on the keyboard is pressed. - * Because of how operating systems handle key repeats, holding - * down a key will cause multiple calls to keyPressed(), because - * the OS repeat takes over. + * Called each time a single key on the keyboard is pressed. Because of how + * operating systems handle key repeats, holding down a key will cause + * multiple calls to keyPressed(), because the OS repeat takes over. *

- * Examples for key handling: - * (Tested on Windows XP, please notify if different on other - * platforms, I have a feeling Mac OS and Linux may do otherwise) + * Examples for key handling: (Tested on Windows XP, please notify if + * different on other platforms, I have a feeling Mac OS and Linux may do + * otherwise) + * * 

    * 1. Pressing 'a' on the keyboard:
    *    keyPressed  with key == 'a' and keyCode == 'A'
@@ -3015,6 +3137,7 @@ public class PApplet implements PConstants {
    *    Java 1.1 (Microsoft VM) passes the TAB key through normally.
    *    Not tested on other platforms or for 1.3.
    *
+ * * @webref input:keyboard * @webBrief Called once every time a key is pressed. * @see PApplet#key @@ -3034,7 +3157,11 @@ public class PApplet implements PConstants { * * The keyReleased() function is called once every time a key is * released. The key that was released will be stored in the key - * variable. See key and keyReleased for more information. + * variable. See key and keyCode for more information.
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events. * * @webref input:keyboard * @webBrief called once every time a key is released. @@ -3053,15 +3180,21 @@ public class PApplet implements PConstants { /** * - * The keyTyped() function is called once every time a key is - * pressed, but action keys such as Ctrl, Shift, and Alt are ignored. - * Because of how operating systems handle key repeats, holding down a key - * will cause multiple calls to keyTyped(), the rate is set by the - * operating system and how each computer is configured. + * The keyTyped() function is called once every time a key is pressed, + * but action keys such as Ctrl, Shift, and Alt are ignored.
+ *
+ * Because of how operating systems handle key repeats, holding down a key may + * cause multiple calls to keyTyped(). The rate of repeat is set by the + * operating system, and may be configured differently on each computer. + *
+ *
+ * Mouse and keyboard events only work when a program has draw(). + * Without draw(), the code is only run once and then stops listening + * for events. * * @webref input:keyboard - * @webBrief Called once every time a key is - * pressed, but action keys such as Ctrl, Shift, and Alt are ignored. + * @webBrief Called once every time a key is pressed, but action keys such as + * Ctrl, Shift, and Alt are ignored. * @see PApplet#keyPressed * @see PApplet#key * @see PApplet#keyCode @@ -3104,7 +3237,7 @@ public class PApplet implements PConstants { * starting an applet. This information is often used for timing animation * sequences. * - * + * *

Advanced

*

* This is a function, rather than a variable, because it may @@ -3148,9 +3281,9 @@ public class PApplet implements PConstants { * Processing communicates with the clock on your computer. The * minute() function returns the current minute as a value from 0 - 59. * - * + * * @webref input:time_date - * @webBrief Processing communicates with the clock on your computer. + * @webBrief Processing communicates with the clock on your computer. * @see PApplet#millis() * @see PApplet#second() * @see PApplet#hour() @@ -3187,7 +3320,7 @@ public class PApplet implements PConstants { * Processing communicates with the clock on your computer. The * day() function returns the current day as a value from 1 - 31. * - * + * *

Advanced

* Get the current day of the month (1 through 31). *

@@ -3195,7 +3328,7 @@ public class PApplet implements PConstants { * or day of the year (1..365) then use java's Calendar.get() * * @webref input:time_date - * @webBrief Processing communicates with the clock on your computer. + * @webBrief Processing communicates with the clock on your computer. * @see PApplet#millis() * @see PApplet#second() * @see PApplet#minute() @@ -3212,7 +3345,7 @@ public class PApplet implements PConstants { * Processing communicates with the clock on your computer. The * month() function returns the current month as a value from 1 - 12. * - * + * * @webref input:time_date * @webBrief Processing communicates with the clock on your computer. * @see PApplet#millis() @@ -3233,10 +3366,9 @@ public class PApplet implements PConstants { * year() function returns the current year as an integer (2003, * 2004, 2005, etc). * - * The year() function returns the current year as an integer (2003, 2004, 2005, etc). * * @webref input:time_date - * @webBrief Processing communicates with the clock on your computer. + * @webBrief Processing communicates with the clock on your computer. * @see PApplet#millis() * @see PApplet#second() * @see PApplet#minute() @@ -3289,15 +3421,16 @@ public class PApplet implements PConstants { /** * - * Specifies the number of frames to be displayed every second. If the - * processor is not fast enough to maintain the specified rate, it will not - * be achieved. For example, the function call frameRate(30) will - * attempt to refresh 30 times a second. It is recommended to set the frame - * rate within setup(). The default rate is 60 frames per second. + * Specifies the number of frames to be displayed every second. For example, + * the function call frameRate(30) will attempt to refresh 30 times a + * second. If the processor is not fast enough to maintain the specified rate, + * the frame rate will not be achieved. Setting the frame rate within + * setup() is recommended. The default rate is 60 frames per second. * * @webref environment * @webBrief Specifies the number of frames to be displayed every second. - * @param fps number of desired frames per second + * @param fps + * number of desired frames per second * @see PApplet#frameRate * @see PApplet#frameCount * @see PApplet#setup() @@ -3339,39 +3472,38 @@ public class PApplet implements PConstants { /** * - * Attempts to open an application or file using your platform's launcher. - * The file parameter is a String specifying the file name and - * location. The location parameter must be a full path name, or the name - * of an executable in the system's PATH. In most cases, using a full path - * is the best option, rather than relying on the system PATH. Be sure to - * make the file executable before attempting to open it (chmod +x). - *

- * The args parameter is a String or String array which is passed to - * the command line. If you have multiple parameters, e.g. an application - * and a document, or a command with multiple switches, use the version - * that takes a String array, and place each individual item in a separate - * element. - *

- * If args is a String (not an array), then it can only be a single file or - * application with no parameters. It's not the same as executing that - * String using a shell. For instance, launch("javac -help") will not work - * properly. - *

+ * Attempts to open an application or file using your platform's launcher. The + * filename parameter is a String specifying the file name and + * location. The location parameter must be a full path name, or the name of + * an executable in the system's PATH. In most cases, using a full path is the + * best option, rather than relying on the system PATH. Be sure to make the + * file executable before attempting to open it (chmod +x).
+ *
+ * This function (roughly) emulates what happens when you double-click an + * application or document in the macOS Finder, the Windows Explorer, or your + * favorite Linux file manager. If you're trying to run command line functions + * directly, use the exec() function instead (see below).
+ *
* This function behaves differently on each platform. On Windows, the * parameters are sent to the Windows shell via "cmd /c". On Mac OS X, the - * "open" command is used (type "man open" in Terminal.app for - * documentation). On Linux, it first tries gnome-open, then kde-open, but - * if neither are available, it sends the command to the shell without any - * alterations. - *

- * For users familiar with Java, this is not quite the same as - * Runtime.exec(), because the launcher command is prepended. Instead, the + * "open" command is used (type "man open" in Terminal.app for documentation). + * On Linux, it first tries gnome-open, then kde-open, but if neither are + * available, it sends the command to the shell and prays that something + * useful happens.
+ *
+ * For users familiar with Java, this is not the same as Runtime.exec(), + * because the launcher command is prepended. Instead, the * exec(String[]) function is a shortcut for - * Runtime.getRuntime.exec(String[]). + * Runtime.getRuntime.exec(String[]). The exec() function is documented + * in the + * JavaDoc + * in the PApplet class. * * @webref input:files - * @webBrief Attempts to open an application or file using your platform's launcher. - * @param args arguments to the launcher, eg. a filename. + * @webBrief Attempts to open an application or file using your platform's + * launcher. + * @param args + * arguments to the launcher, eg. a filename. * @usage Application */ static public Process launch(String... args) { @@ -3765,18 +3897,44 @@ public class PApplet implements PConstants { /** - * Launch a new thread and call the specified function from that new thread. - * This is a very simple way to do a thread without needing to get into - * classes, runnables, etc. - *

- * Note that the function being called must be public. Inside the PDE, - * 'public' is automatically added, but when used without the preprocessor, - * (like from Eclipse) you'll have to do it yourself. + * Processing sketches follow a specific sequence of steps: setup() + * first, followed by draw() over and over and over again in a loop. A + * thread is also a series of steps with a beginning, a middle, and an end. A + * Processing sketch is a single thread, often referred to as the "Animation" + * thread. Other threads' sequences, however, can run independently of the + * main animation loop. In fact, you can launch any number of threads at one + * time, and they will all run concurrently.
+ *
+ * You cannot draw to the screen from a function called by thread(). + * Because it runs independently, the code will not be synchronized to the + * animation thread, causing strange or at least inconsistent results. Use + * thread() to load files or do other tasks that take time. When the + * task is finished, set a variable that indicates the task is complete, and + * check that from inside your draw() method.
+ *
+ * Processing uses threads quite often, such as with library functions like + * captureEvent() and movieEvent(). These functions are + * triggered by a different thread running behind the scenes, and they alert + * Processing whenever they have something to report. This is useful when you + * need to perform a task that takes too long and would slow down the main + * animation's frame rate, such as grabbing data from the network. If a + * separate thread gets stuck or has an error, the entire program won't grind + * to a halt, since the error only stops that individual thread.
+ *
+ * Writing your own thread can be a complex endeavor that involves extending + * the Java Thread + * class. However, the thread() method is a quick and dirty way to + * implement a simple thread in Processing. By passing in a String that + * matches the name of a function declared elsewhere in the sketch, Processing + * will execute that function in a separate thread. * * @webref structure - * @webBrief Launch a new thread and call the specified function from that new thread. + * @webBrief Launch a new thread and call the specified function from that new + * thread. * @usage Application - * @param name name of the function to be executed in a separate thread + * @param name + * name of the function to be executed in a separate thread * @see PApplet#setup() * @see PApplet#draw() * @see PApplet#loop() @@ -3795,21 +3953,23 @@ public class PApplet implements PConstants { /** * - * Saves an image from the display window. Images are saved in TIFF, TARGA, - * JPEG, and PNG format depending on the extension within the - * filename parameter. For example, "image.tif" will have a TIFF - * image and "image.png" will save a PNG image. If no extension is included - * in the filename, the image will save in TIFF format and .tif will - * be added to the name. These files are saved to the sketch's folder, - * which may be opened by selecting "Show sketch folder" from the "Sketch" - * menu. It is not possible to use save() while running the program - * in a web browser. - *
images saved from the main drawing window will be opaque. To save + * Saves an image from the display window. Append a file extension to the name + * of the file, to indicate the file format to be used: either TIFF (.tif), + * TARGA (.tga), JPEG (.jpg), or PNG (.png). If no extension is included in + * the filename, the image will save in TIFF format and .tif will be + * added to the name. These files are saved to the sketch's folder, which may + * be opened by selecting "Show sketch folder" from the "Sketch" menu. + * Alternatively, the files can be saved to any location on the computer by + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows).
+ *
+ * All images saved from the main drawing window will be opaque. To save * images without a background, use createGraphics(). * * @webref output:image * @webBrief Saves an image from the display window. - * @param filename any sequence of letters and numbers + * @param filename + * any sequence of letters and numbers * @see PApplet#saveFrame() * @see PApplet#createGraphics(int, int, String) */ @@ -3834,34 +3994,36 @@ public class PApplet implements PConstants { * * Saves a numbered sequence of images, one image each time the function is * run. To save an image that is identical to the display window, run the - * function at the end of draw() or within mouse and key events such - * as mousePressed() and keyPressed(). If saveFrame() - * is called without parameters, it will save the files as screen-0000.tif, - * screen-0001.tif, etc. It is possible to specify the name of the sequence - * with the filename parameter and make the choice of saving TIFF, - * TARGA, PNG, or JPEG files with the ext parameter. These image - * sequences can be loaded into programs such as Apple's QuickTime software - * and made into movies. These files are saved to the sketch's folder, - * which may be opened by selecting "Show sketch folder" from the "Sketch" - * menu.
+ * function at the end of draw() or within mouse and key events such as + * mousePressed() and keyPressed(). Use the Movie Maker program + * in the Tools menu to combine these images to a movie.
+ *
+ * If saveFrame() is used without parameters, it will save files as + * screen-0000.tif, screen-0001.tif, and so on. You can specify the name of + * the sequence with the filename parameter, including hash marks + * (####), which will be replaced by the current frameCount value. (The + * number of hash marks is used to determine how many digits to include in the + * file names.) Append a file extension, to indicate the file format to be + * used: either TIFF (.tif), TARGA (.tga), JPEG (.jpg), or PNG (.png). Image + * files are saved to the sketch's folder, which may be opened by selecting + * "Show Sketch Folder" from the "Sketch" menu.
+ *
+ * Alternatively, the files can be saved to any location on the computer by + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows).
*
- * It is not possible to use saveXxxxx() functions inside a web browser - * unless the sketch is signed applet. To - * save a file back to a server, see the save to - * web code snippet on the Processing Wiki.
- *
* All images saved from the main drawing window will be opaque. To save * images without a background, use createGraphics(). * * @webref output:image - * @webBrief Saves a numbered sequence of images, one image each time the function is - * run. + * @webBrief Saves a numbered sequence of images, one image each time the + * function is run. * @see PApplet#save(String) * @see PApplet#createGraphics(int, int, String, String) * @see PApplet#frameCount - * @param filename any sequence of letters or numbers that ends with either ".tif", ".tga", ".jpg", or ".png" + * @param filename + * any sequence of letters or numbers that ends with either ".tif", + * ".tga", ".jpg", or ".png" */ public void saveFrame(String filename) { try { @@ -3922,31 +4084,38 @@ public class PApplet implements PConstants { /** * - * Sets the cursor to a predefined symbol, an image, or makes it visible if - * already hidden. If you are trying to set an image as the cursor, it is - * recommended to make the size 16x16 or 32x32 pixels. It is not possible - * to load an image as the cursor if you are exporting your program for the - * Web and not all MODES work with all Web browsers. The values for - * parameters x and y must be less than the dimensions of the image. - *

- * Setting or hiding the cursor generally does not work with "Present" mode - * (when running full-screen). + * Sets the cursor to a predefined symbol or an image, or makes it visible if + * already hidden. If you are trying to set an image as the cursor, the + * recommended size is 16x16 or 32x32 pixels. The values for parameters + * x and y must be less than the dimensions of the image.
+ *
+ * Setting or hiding the cursor does not generally work with "Present" mode + * (when running full-screen).
+ *
+ * With the P2D and P3D renderers, a generic set of cursors are used because + * the OpenGL renderer doesn't have access to the default cursor images for + * each platform + * (Issue + * 3791). * - *

Advanced

- * Set a custom cursor to an image with a specific hotspot. - * Only works with JDK 1.2 and later. - * Currently seems to be broken on Java 1.4 for Mac OS X + *

Advanced

Set a custom cursor to an image with a specific hotspot. + * Only works with JDK 1.2 and later. Currently seems to be broken on Java 1.4 + * for Mac OS X *

- * Based on code contributed by Amit Pitaru, plus additional - * code to handle Java versions via reflection by Jonathan Feinberg. - * Reflection removed for release 0128 and later. + * Based on code contributed by Amit Pitaru, plus additional code to handle + * Java versions via reflection by Jonathan Feinberg. Reflection removed for + * release 0128 and later. + * * @webref environment - * @webBrief Sets the cursor to a predefined symbol, an image, or makes it visible if - * already hidden. + * @webBrief Sets the cursor to a predefined symbol, an image, or makes it + * visible if already hidden. * @see PApplet#noCursor() - * @param img any variable of type PImage - * @param x the horizontal active spot of the cursor - * @param y the vertical active spot of the cursor + * @param img + * any variable of type PImage + * @param x + * the horizontal active spot of the cursor + * @param y + * the vertical active spot of the cursor */ public void cursor(PImage img, int x, int y) { surface.setCursor(img, x, y); @@ -3983,31 +4152,32 @@ public class PApplet implements PConstants { ////////////////////////////////////////////////////////////// /** - * - * Writes to the console area of the Processing environment. This is often - * helpful for looking at the data a program is producing. The companion - * function println() works like print(), but creates a new - * line of text for each call to the function. Individual elements can be - * separated with quotes ("") and joined with the addition operator (+).
- *
- * Beginning with release 0125, to print the contents of an array, use - * println(). There's no sensible way to do a print() of an array, - * because there are too many possibilities for how to separate the data - * (spaces, commas, etc). If you want to print an array as a single line, - * use join(). With join(), you can choose any delimiter you - * like and print() the result.
- *
- * Using print() on an object will output null, a memory - * location that may look like "@10be08," or the result of the - * toString() method from the object that's being printed. Advanced - * users who want more useful output when calling print() on their - * own classes can add a toString() method to the class that returns - * a String. - * + * + * The print() function writes to the console area, the black rectangle + * at the bottom of the Processing environment. This function is often helpful + * for looking at the data a program is producing. The companion function + * println() works like print(), but creates a new line of text + * for each call to the function. More than one parameter can be passed into the + * function by separating them with commas. Alternatively, individual elements + * can be separated with quotes ("") and joined with the addition operator + * (+).
+ *
+ * Using print() on an object will output null, a memory location + * that may look like "@10be08," or the result of the toString() method + * from the object that's being printed. Advanced users who want more useful + * output when calling print() on their own classes can add a + * toString() method to the class that returns a String.
+ *
+ * Note that the console is relatively slow. It works well for occasional + * messages, but does not support high-speed, real-time output (such as at 60 + * frames per second). It should also be noted, that a print() within a for loop + * can sometimes lock up the program, and cause the sketch to freeze. + * * @webref output:text_area * @webBrief Writes to the console area of the Processing environment. * @usage IDE - * @param what data to print to console + * @param what + * data to print to console * @see PApplet#println() * @see PApplet#printArray(Object) * @see PApplet#join(String[], char) @@ -4085,24 +4255,29 @@ public class PApplet implements PConstants { /** * - * Writes to the text area of the Processing environment's console. This is - * often helpful for looking at the data a program is producing. Each call - * to this function creates a new line of output. Individual elements can - * be separated with quotes ("") and joined with the string concatenation - * operator (+). See print() for more about what to expect in the output. - *

println() on an array (by itself) will write the - * contents of the array to the console. This is often helpful for looking - * at the data a program is producing. A new line is put between each - * element of the array. This function can only print one dimensional - * arrays. For arrays with higher dimensions, the result will be closer to - * that of print(). + * The println() function writes to the console area, the black + * rectangle at the bottom of the Processing environment. This function is + * often helpful for looking at the data a program is producing. Each call to + * this function creates a new line of output. More than one parameter can be + * passed into the function by separating them with commas. Alternatively, + * individual elements can be separated with quotes ("") and joined with the + * addition operator (+).
+ *
+ * Before Processing 2.1, println() was used to write array data to the + * console. Now, use printArray() to write array data to the + * console.
+ *
+ * Note that the console is relatively slow. It works well for occasional + * messages, but does not support high-speed, real-time output (such as at 60 + * frames per second). It should also be noted, that a println() within a for + * loop can sometimes lock up the program, and cause the sketch to freeze. * - * @webref output:text_area - * @webBrief Writes to the text area of the Processing environment's console. - * @usage IDE - * @see PApplet#print(byte) - * @see PApplet#printArray(Object) - */ + * @webref output:text_area + * @webBrief Writes to the text area of the Processing environment's console. + * @usage IDE + * @see PApplet#print(byte) + * @see PApplet#printArray(Object) + */ static public void println() { System.out.println(); } @@ -4194,17 +4369,17 @@ public class PApplet implements PConstants { /** * - * The printArray() function writes array data to the text - * area of the Processing environment's console. A new line - * is put between each element of the array. This function + * The printArray() function writes array data to the text + * area of the Processing environment's console. A new line + * is put between each element of the array. This function * can only print one dimensional arrays. - * Note that the console is relatively slow. It works well - * for occasional messages, but does not support high-speed, + * Note that the console is relatively slow. It works well + * for occasional messages, but does not support high-speed, * real-time output (such as at 60 frames per second). * - * + * * @webref output:text_area - * @webBrief The printArray() function writes array data to the text + * @webBrief The printArray() function writes array data to the text * area of the Processing environment's console. * @param what one-dimensional array * @usage IDE @@ -4330,7 +4505,7 @@ public class PApplet implements PConstants { * Calculates the absolute value (magnitude) of a number. The absolute * value of a number is always positive. * - * + * * @webref math:calculation * @webBrief Calculates the absolute value (magnitude) of a number. * @param n number to compute @@ -4421,15 +4596,19 @@ public class PApplet implements PConstants { } /** - * - * Determines the largest value in a sequence of numbers. - * - * @webref math:calculation - * @webBrief Determines the largest value in a sequence of numbers. - * @param a first number to compare - * @param b second number to compare - * @see PApplet#min(float, float, float) - */ + * + * Determines the largest value in a sequence of numbers, and then returns that + * value. max() accepts either two or three float or int + * values as parameters, or an array of any length. + * + * @webref math:calculation + * @webBrief Determines the largest value in a sequence of numbers. + * @param a + * first number to compare + * @param b + * second number to compare + * @see PApplet#min(float, float, float) + */ static public final int max(int a, int b) { return (a > b) ? a : b; } @@ -4523,16 +4702,21 @@ public class PApplet implements PConstants { } /** - * - * Determines the smallest value in a sequence of numbers. - * - * @webref math:calculation - * @webBrief Determines the smallest value in a sequence of numbers. - * @param a first number - * @param b second number - * @param c third number - * @see PApplet#max(float, float, float) - */ + * + * Determines the smallest value in a sequence of numbers, and then returns that + * value. min() accepts either two or three float or int + * values as parameters, or an array of any length. + * + * @webref math:calculation + * @webBrief Determines the smallest value in a sequence of numbers. + * @param a + * first number + * @param b + * second number + * @param c + * third number + * @see PApplet#max(float, float, float) + */ static public final float min(float a, float b, float c) { return (a < b) ? ((a < c) ? a : c) : ((b < c) ? b : c); } @@ -4597,7 +4781,7 @@ public class PApplet implements PConstants { /** * * Constrains a value to not exceed a maximum and minimum value. - * + * * @webref math:calculation * @webBrief Constrains a value to not exceed a maximum and minimum value. * @param amt the value to constrain @@ -4616,7 +4800,7 @@ public class PApplet implements PConstants { * Calculates the sine of an angle. This function expects the values of the * angle parameter to be provided in radians (values from 0 to * 6.28). Values are returned in the range -1 to 1. - * + * * @webref math:trigonometry * @webBrief Calculates the sine of an angle. * @param angle an angle in radians @@ -4759,7 +4943,7 @@ public class PApplet implements PConstants { * 360 degrees in a circle and 2*PI radians in a circle. For example, * 90° = PI/2 = 1.5707964. All trigonometric functions in Processing * require their parameters to be specified in radians. - * + * * @webref math:trigonometry * @webBrief Converts a degree measurement to its corresponding value in radians. * @param degrees degree value to convert to radians @@ -4802,16 +4986,17 @@ public class PApplet implements PConstants { } /** - * - * Calculates the integer closest to the value parameter. For - * example, round(9.2) returns the value 9. - * - * @webref math:calculation - * @webBrief Calculates the integer closest to the value parameter. - * @param n number to round - * @see PApplet#floor(float) - * @see PApplet#ceil(float) - */ + * + * Calculates the integer closest to the n parameter. For example, + * round(133.8) returns the value 134. + * + * @webref math:calculation + * @webBrief Calculates the integer closest to the value parameter. + * @param n + * number to round + * @see PApplet#floor(float) + * @see PApplet#ceil(float) + */ static public final int round(float n) { return Math.round(n); } @@ -4888,17 +5073,21 @@ public class PApplet implements PConstants { /** * * Normalizes a number from another range into a value between 0 and 1. - *

- * Identical to map(value, low, high, 0, 1); - *

- * Numbers outside the range are not clamped to 0 and 1, because - * out-of-range values are often intentional and useful. + * Identical to map(value, low, high, 0, 1).
+ *
+ * Numbers outside of the range are not clamped to 0 and 1, because + * out-of-range values are often intentional and useful. (See the second + * example above.) * * @webref math:calculation - * @webBrief Normalizes a number from another range into a value between 0 and 1. - * @param value the incoming value to be converted - * @param start lower bound of the value's current range - * @param stop upper bound of the value's current range + * @webBrief Normalizes a number from another range into a value between 0 and + * 1. + * @param value + * the incoming value to be converted + * @param start + * lower bound of the value's current range + * @param stop + * upper bound of the value's current range * @see PApplet#map(float, float, float, float, float) * @see PApplet#lerp(float, float, float) */ @@ -4908,21 +5097,28 @@ public class PApplet implements PConstants { /** * - * Re-maps a number from one range to another. In the example above, - * the number '25' is converted from a value in the range 0..100 into - * a value that ranges from the left edge (0) to the right edge (width) - * of the screen. - *

- * Numbers outside the range are not clamped to 0 and 1, because - * out-of-range values are often intentional and useful. + * Re-maps a number from one range to another.
+ *
+ * In the first example above, the number 25 is converted from a value in the + * range of 0 to 100 into a value that ranges from the left edge of the window + * (0) to the right edge (width).
+ *
+ * As shown in the second example, numbers outside of the range are not + * clamped to the minimum and maximum parameters values, because out-of-range + * values are often intentional and useful. * * @webref math:calculation * @webBrief Re-maps a number from one range to another. - * @param value the incoming value to be converted - * @param start1 lower bound of the value's current range - * @param stop1 upper bound of the value's current range - * @param start2 lower bound of the value's target range - * @param stop2 upper bound of the value's target range + * @param value + * the incoming value to be converted + * @param start1 + * lower bound of the value's current range + * @param stop1 + * upper bound of the value's current range + * @param start2 + * lower bound of the value's target range + * @param stop2 + * upper bound of the value's target range * @see PApplet#norm(float, float, float) * @see PApplet#lerp(float, float, float) */ @@ -5017,21 +5213,24 @@ public class PApplet implements PConstants { /** * - * Generates random numbers. Each time the random() function is - * called, it returns an unexpected value within the specified range. If - * one parameter is passed to the function it will return a float - * between zero and the value of the high parameter. The function - * call random(5) returns values between 0 and 5 (starting at zero, - * up to but not including 5). If two parameters are passed, it will return - * a float with a value between the the parameters. The function - * call random(-5, 10.2) returns values starting at -5 up to (but - * not including) 10.2. To convert a floating-point random number to an - * integer, use the int() function. + * Generates random numbers. Each time the random() function is called, + * it returns an unexpected value within the specified range. If only one + * parameter is passed to the function, it will return a float between zero + * and the value of the high parameter. For example, random(5) + * returns values between 0 and 5 (starting at zero, and up to, but not + * including, 5).
+ *
+ * If two parameters are specified, the function will return a float with a + * value between the two values. For example, random(-5, 10.2) returns + * values starting at -5 and up to (but not including) 10.2. To convert a + * floating-point random number to an integer, use the int() function. * * @webref math:random * @webBrief Generates random numbers. - * @param low lower limit - * @param high upper limit + * @param low + * lower limit + * @param high + * upper limit * @see PApplet#randomSeed(long) * @see PApplet#noise(float, float, float) */ @@ -5049,19 +5248,20 @@ public class PApplet implements PConstants { /** - * - * Sets the seed value for random(). By default, random() - * produces different results each time the program is run. Set the - * value parameter to a constant to return the same pseudo-random - * numbers each time the software is run. - * - * @webref math:random - * @webBrief Sets the seed value for random(). - * @param seed seed value - * @see PApplet#random(float,float) - * @see PApplet#noise(float, float, float) - * @see PApplet#noiseSeed(long) - */ + * + * Sets the seed value for random(). By default, random() + * produces different results each time the program is run. Set the seed + * parameter to a constant to return the same pseudo-random numbers each time + * the software is run. + * + * @webref math:random + * @webBrief Sets the seed value for random(). + * @param seed + * seed value + * @see PApplet#random(float,float) + * @see PApplet#noise(float, float, float) + * @see PApplet#noiseSeed(long) + */ public final void randomSeed(long seed) { if (internalRandom == null) { internalRandom = new Random(); @@ -5119,38 +5319,49 @@ public class PApplet implements PConstants { /** * - * Returns the Perlin noise value at specified coordinates. Perlin noise is - * a random sequence generator producing a more natural ordered, harmonic - * succession of numbers compared to the standard random() function. - * It was invented by Ken Perlin in the 1980s and been used since in - * graphical applications to produce procedural textures, natural motion, - * shapes, terrains etc.

The main difference to the - * random() function is that Perlin noise is defined in an infinite - * n-dimensional space where each pair of coordinates corresponds to a - * fixed semi-random value (fixed only for the lifespan of the program). + * Returns the Perlin noise value at specified coordinates. Perlin noise is a + * random sequence generator producing a more natural, harmonic succession of + * numbers than that of the standard random() function. It was + * developed by Ken Perlin in the 1980s and has been used in graphical + * applications to generate procedural textures, shapes, terrains, and other + * seemingly organic forms.
+ *
+ * In contrast to the random() function, Perlin noise is defined in an + * infinite n-dimensional space, in which each pair of coordinates corresponds + * to a fixed semi-random value (fixed only for the lifespan of the program). * The resulting value will always be between 0.0 and 1.0. Processing can - * compute 1D, 2D and 3D noise, depending on the number of coordinates - * given. The noise value can be animated by moving through the noise space - * as demonstrated in the example above. The 2nd and 3rd dimension can also - * be interpreted as time.

The actual noise is structured - * similar to an audio signal, in respect to the function's use of - * frequencies. Similar to the concept of harmonics in physics, perlin - * noise is computed over several octaves which are added together for the - * final result.

Another way to adjust the character of the - * resulting sequence is the scale of the input coordinates. As the - * function works within an infinite space the value of the coordinates - * doesn't matter as such, only the distance between successive coordinates - * does (eg. when using noise() within a loop). As a general rule - * the smaller the difference between coordinates, the smoother the - * resulting noise sequence will be. Steps of 0.005-0.03 work best for most - * applications, but this will differ depending on use. + * compute 1D, 2D and 3D noise, depending on the number of coordinates given. + * The noise value can be animated by moving through the noise space, as + * demonstrated in the first example above. The 2nd and 3rd dimensions can + * also be interpreted as time.
+ *
+ * The actual noise structure is similar to that of an audio signal, in + * respect to the function's use of frequencies. Similar to the concept of + * harmonics in physics, Perlin noise is computed over several octaves which + * are added together for the final result.
+ *
+ * Another way to adjust the character of the resulting sequence is the scale + * of the input coordinates. As the function works within an infinite space, + * the value of the coordinates doesn't matter as such; only the + * distance between successive coordinates is important (such as when + * using noise() within a loop). As a general rule, the smaller the + * difference between coordinates, the smoother the resulting noise sequence. + * Steps of 0.005-0.03 work best for most applications, but this will differ + * depending on use.
+ *
+ * There have been debates over the accuracy of the implementation of noise in + * Processing. For clarification, it's an implementation of "classic Perlin + * noise" from 1983, and not the newer "simplex noise" method from 2001. + * * - * * @webref math:random * @webBrief Returns the Perlin noise value at specified coordinates. - * @param x x-coordinate in noise space - * @param y y-coordinate in noise space - * @param z z-coordinate in noise space + * @param x + * x-coordinate in noise space + * @param y + * y-coordinate in noise space + * @param z + * z-coordinate in noise space * @see PApplet#noiseSeed(long) * @see PApplet#noiseDetail(int, float) * @see PApplet#random(float,float) @@ -5237,24 +5448,27 @@ public class PApplet implements PConstants { /** * * Adjusts the character and level of detail produced by the Perlin noise - * function. Similar to harmonics in physics, noise is computed over - * several octaves. Lower octaves contribute more to the output signal and - * as such define the overal intensity of the noise, whereas higher octaves - * create finer grained details in the noise sequence. By default, noise is - * computed over 4 octaves with each octave contributing exactly half than - * its predecessor, starting at 50% strength for the 1st octave. This - * falloff amount can be changed by adding an additional function - * parameter. Eg. a falloff factor of 0.75 means each octave will now have - * 75% impact (25% less) of the previous lower octave. Any value between - * 0.0 and 1.0 is valid, however note that values greater than 0.5 might - * result in greater than 1.0 values returned by noise().

By changing these parameters, the signal created by the noise() + * function. Similar to harmonics in physics, noise is computed over several + * octaves. Lower octaves contribute more to the output signal and as such + * define the overall intensity of the noise, whereas higher octaves create + * finer-grained details in the noise sequence.
+ *
+ * By default, noise is computed over 4 octaves with each octave contributing + * exactly half than its predecessor, starting at 50% strength for the first + * octave. This falloff amount can be changed by adding an additional function + * parameter. For example, a falloff factor of 0.75 means each octave will now + * have 75% impact (25% less) of the previous lower octave. While any number + * between 0.0 and 1.0 is valid, note that values greater than 0.5 may result + * in noise() returning values greater than 1.0.
+ *
+ * By changing these parameters, the signal created by the noise() * function can be adapted to fit very specific needs and characteristics. * * @webref math:random - * @webBrief Adjusts the character and level of detail produced by the Perlin noise - * function. - * @param lod number of octaves to be used by the noise + * @webBrief Adjusts the character and level of detail produced by the Perlin + * noise function. + * @param lod + * number of octaves to be used by the noise * @see PApplet#noise(float, float, float) */ public void noiseDetail(int lod) { @@ -5299,38 +5513,46 @@ public class PApplet implements PConstants { /** * - * Loads an image into a variable of type PImage. Four types of - * images ( .gif, .jpg, .tga, .png) images may - * be loaded. To load correctly, images must be located in the data - * directory of the current sketch. In most cases, load all images in - * setup() to preload them at the start of the program. Loading - * images inside draw() will reduce the speed of a program.
- *
filename parameter can also be a URL to a file found - * online. For security reasons, a Processing sketch found online can only - * download files from the same server from which it came. Getting around - * this restriction requires a signed - * applet.
- *
extension parameter is used to determine the image type in - * cases where the image filename does not end with a proper extension. - * Specify the extension as the second parameter to loadImage(), as - * shown in the third example on this page.
- *
an image is not loaded successfully, the null value is + * Loads an image into a variable of type PImage. Four types of images + * ( .gif, .jpg, .tga, .png) images may be loaded. + * To load correctly, images must be located in the data directory of the + * current sketch.
+ *
+ * In most cases, load all images in setup() to preload them at the + * start of the program. Loading images inside draw() will reduce the + * speed of a program. Images cannot be loaded outside setup() unless + * they're inside a function that's called after setup() has already + * run.
+ *
+ * Alternatively, the file maybe be loaded from anywhere on the local computer + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows), or the filename parameter can be a URL for a + * file found on a network.
+ *
+ * If the file is not available or an error occurs, null will be * returned and an error message will be printed to the console. The error * message does not halt the program, however the null value may cause a - * NullPointerException if your code does not check whether the value - * returned from loadImage() is null.
- *
on the type of error, a PImage object may still be + * NullPointerException if your code does not check whether the value returned + * is null.
+ *
+ * The extension parameter is used to determine the image type in cases + * where the image filename does not end with a proper extension. Specify the + * extension as the second parameter to loadImage(), as shown in the + * third example on this page. Note that CMYK images are not supported.
+ *
+ * Depending on the type of error, a PImage object may still be * returned, but the width and height of the image will be set to -1. This * happens if bad image data is returned or cannot be decoded properly. * Sometimes this happens with image URLs that produce a 403 error or that - * redirect to a password prompt, because loadImage() will attempt - * to interpret the HTML as image data. + * redirect to a password prompt, because loadImage() will attempt to + * interpret the HTML as image data. + * * - * * @webref image:loading_displaying * @webBrief Loads an image into a variable of type PImage. - * @param filename name of file to load, can be .gif, .jpg, .tga, or a handful of other image types depending on your platform + * @param filename + * name of file to load, can be .gif, .jpg, .tga, or a handful of + * other image types depending on your platform * @see PImage * @see PGraphics#image(PImage, float, float, float, float) * @see PGraphics#imageMode(int) @@ -5368,23 +5590,27 @@ public class PApplet implements PConstants { /** * - * This function load images on a separate thread so that your sketch does - * not freeze while images load during setup(). While the image is - * loading, its width and height will be 0. If an error occurs while - * loading the image, its width and height will be set to -1. You'll know - * when the image has loaded properly because its width and height will be - * greater than 0. Asynchronous image loading (particularly when - * downloading from a server) can dramatically improve performance.
- *
extension parameter is used to determine the image type in - * cases where the image filename does not end with a proper extension. - * Specify the extension as the second parameter to requestImage(). + * This function loads images on a separate thread so that your sketch doesn't + * freeze while images load during setup(). While the image is loading, + * its width and height will be 0. If an error occurs while loading the image, + * its width and height will be set to -1. You'll know when the image has + * loaded properly because its width and height will be greater + * than 0. Asynchronous image loading (particularly when downloading from a + * server) can dramatically improve performance.
+ *
+ * The extension parameter is used to determine the image type in cases + * where the image filename does not end with a proper extension. Specify the + * extension as the second parameter to requestImage(). + * * - * * @webref image:loading_displaying - * @webBrief Loads images on a separate thread so that your sketch does - * not freeze while images load during setup(). - * @param filename name of the file to load, can be .gif, .jpg, .tga, or a handful of other image types depending on your platform - * @param extension the type of image to load, for example "png", "gif", "jpg" + * @webBrief Loads images on a separate thread so that your sketch does not + * freeze while images load during setup(). + * @param filename + * name of the file to load, can be .gif, .jpg, .tga, or a handful of + * other image types depending on your platform + * @param extension + * the type of image to load, for example "png", "gif", "jpg" * @see PImage * @see PApplet#loadImage(String, String) */ @@ -5450,17 +5676,17 @@ public class PApplet implements PConstants { /** - * Reads the contents of a file or URL and creates an XML - * object with its values. If a file is specified, it must - * be located in the sketch's "data" folder. The filename + * Reads the contents of a file or URL and creates an XML + * object with its values. If a file is specified, it must + * be located in the sketch's "data" folder. The filename * parameter can also be a URL to a file found online.

- * All files loaded and saved by the Processing API use - * UTF-8 encoding. If you need to load an XML file that's + * All files loaded and saved by the Processing API use + * UTF-8 encoding. If you need to load an XML file that's * not in UTF-8 format, see the * developer's reference for the XML object. * @webref input:files - * @webBrief Reads the contents of a file or URL and creates an XML - * object with its values. + * @webBrief Reads the contents of a file or URL and creates an XML + * object with its values. * @param filename name of a file in the data folder or a URL. * @see XML * @see PApplet#parseXML(String) @@ -5495,21 +5721,24 @@ public class PApplet implements PConstants { /** - * Takes a String, parses its contents, and returns - * an XML object. If the String does not contain XML - * data or cannot be parsed, a null value is returned. - * parseXML() is most useful when pulling data dynamically, - * such as from third-party APIs. Normally, API results - * would be saved to a String, and then can be converted - * to a structured XML object using parseXML(). Be sure - * to check if null is returned before performing - * operations on the new XML object, in case the String - * content could not be parsed. - * If your data already exists as an XML file in the data - * folder, it is simpler to use loadXML(). + * Takes a String, parses its contents, and returns an XML object. If the + * String does not contain XML data or cannot be parsed, a null value is + * returned.
+ *
+ * parseXML() is most useful when pulling data dynamically, such as + * from third-party APIs. Normally, API results would be saved to a String, + * and then can be converted to a structured XML object using + * parseXML(). Be sure to check if null is returned before performing + * operations on the new XML object, in case the String content could not be + * parsed.
+ *
+ * If your data already exists as an XML file in the data folder, it is + * simpler to use loadXML(). + * * @webref input:files * @webBrief Converts String content to an XML object - * @param xmlString the content to be parsed as XML + * @param xmlString + * the content to be parsed as XML * @return an XML object, or null * @see XML * @see PApplet#loadXML(String) @@ -5531,20 +5760,22 @@ public class PApplet implements PConstants { /** - * Writes the contents of an XML object to a file. - * By default, this file is saved to the sketch's - * folder. This folder is opened by selecting "Show - * Sketch Folder" from the "Sketch" menu. - * Alternatively, the file can be saved to any location - * on the computer by using an absolute path (something - * that starts with / on Unix and Linux, or a drive - * letter on Windows). - * All files loaded and saved by the Processing API use - * UTF-8 encoding. + * Writes the contents of an XML object to a file. By default, this file is + * saved to the sketch's folder. This folder is opened by selecting "Show + * Sketch Folder" from the "Sketch" menu.
+ *
+ * Alternatively, the file can be saved to any location on the computer by + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows).
+ *
+ * All files loaded and saved by the Processing API use UTF-8 encoding. + * * @webref output:files * @webBrief Writes the contents of an XML object to a file. - * @param xml the XML object to save to disk - * @param filename name of the file to write to + * @param xml + * the XML object to save to disk + * @param filename + * name of the file to write to * @see XML * @see PApplet#loadXML(String) * @see PApplet#parseXML(String) @@ -5561,24 +5792,25 @@ public class PApplet implements PConstants { } /** - * Takes a String, parses its contents, and returns - * a JSONObject. If the String does not contain - * JSONObject data or cannot be parsed, a null - * value is returned.

- * parseJSONObject() is most useful when pulling data - * dynamically, such as from third-party APIs. Normally, API - * results would be saved to a String, and then can be - * converted to a structured JSONObject using - * parseJSONObject(). Be sure to check if null - * is returned before performing operations on the new - * JSONObject in case the String content could - * not be parsed.

- * If your data already exists as a JSON file in the - * data folder, it is simpler to use loadJSONObject(). + * Takes a String, parses its contents, and returns a + * JSONObject. If the String does not contain JSONObject + * data or cannot be parsed, a null value is returned.
+ *
+ * parseJSONObject() is most useful when pulling data dynamically, such + * as from third-party APIs. Normally, API results would be saved to a + * String, and then can be converted to a structured JSONObject + * using parseJSONObject(). Be sure to check if null is returned + * before performing operations on the new JSONObject in case the + * String content could not be parsed.
+ *
+ * If your data already exists as a JSON file in the data folder, it is + * simpler to use loadJSONObject(). + * * @webref input:files - * @webBrief Takes a String, parses its contents, and returns - * a JSONObject. - * @param input String to parse as a JSONObject + * @webBrief Takes a String, parses its contents, and returns a + * JSONObject. + * @param input + * String to parse as a JSONObject * @see PApplet#loadJSONObject(String) * @see PApplet#saveJSONObject(JSONObject, String) */ @@ -5588,13 +5820,16 @@ public class PApplet implements PConstants { /** - * Loads a JSON from the data folder or a URL, and returns a - * JSONObject.

+ * Loads a JSON from the data folder or a URL, and returns a + * JSONObject.
+ *
* All files loaded and saved by the Processing API use UTF-8 encoding. + * * @webref input:files - * @webBrief Loads a JSON from the data folder or a URL, and returns a - * JSONObject. - * @param filename name of a file in the data folder or a URL + * @webBrief Loads a JSON from the data folder or a URL, and returns a + * JSONObject. + * @param filename + * name of a file in the data folder or a URL * @see JSONObject * @see JSONArray * @see PApplet#loadJSONArray(String) @@ -5631,20 +5866,22 @@ public class PApplet implements PConstants { /** - * Writes the contents of a JSONObject object to - * a file. By default, this file is saved to the sketch's - * folder. This folder is opened by selecting "Show Sketch - * Folder" from the "Sketch" menu.

- * Alternatively, the file can be saved to any location on - * the computer by using an absolute path (something that - * starts with / on Unix and Linux, or a drive letter on - * Windows).

+ * Writes the contents of a JSONObject object to a file. By default, + * this file is saved to the sketch's folder. This folder is opened by + * selecting "Show Sketch Folder" from the "Sketch" menu.
+ *
+ * Alternatively, the file can be saved to any location on the computer by + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows).
+ *
* All files loaded and saved by the Processing API use UTF-8 encoding. + * * @webref output:files - * @webBrief Writes the contents of a JSONObject object to - * a file. - * @param json the JSONObject to save - * @param filename the name of the file to save to + * @webBrief Writes the contents of a JSONObject object to a file. + * @param json + * the JSONObject to save + * @param filename + * the name of the file to save to * @see JSONObject * @see JSONArray * @see PApplet#loadJSONObject(String) @@ -5664,50 +5901,46 @@ public class PApplet implements PConstants { } /** - * Takes a String, parses its contents, and returns a JSONArray. - * If the String does not contain JSONArray data or cannot be - * parsed, a null value is returned.

- * parseJSONArray() is most useful when pulling data dynamically, - * such as from third-party APIs. Normally, API results would be saved to a - * String, and then can be converted to a structured JSONArray - * using parseJSONArray(). Be sure to check if null is returned - * before performing operations on the new JSONArray in case the - * String content could not be parsed.

- * If your data already exists as a JSON file in the data folder, it - * is simpler to use loadJSONArray(). - * @webref input:files - * @webBrief - * @param input String to parse as a JSONArray - * @see JSONObject - * @see PApplet#loadJSONObject(String) - * @see PApplet#saveJSONObject(JSONObject, String) - */ + * Takes a String, parses its contents, and returns a JSONArray. + * If the String does not contain JSONArray data or cannot be + * parsed, a null value is returned.
+ *
+ * parseJSONArray() is most useful when pulling data dynamically, such as + * from third-party APIs. Normally, API results would be saved to a + * String, and then can be converted to a structured JSONArray + * using parseJSONArray(). Be sure to check if null is returned + * before performing operations on the new JSONArray in case the + * String content could not be parsed.
+ *
+ * If your data already exists as a JSON file in the data folder, it is + * simpler to use loadJSONArray(). + * + * @webref input:files + * @webBrief + * @param input + * String to parse as a JSONArray + * @see JSONObject + * @see PApplet#loadJSONObject(String) + * @see PApplet#saveJSONObject(JSONObject, String) + */ public JSONArray parseJSONArray(String input) { return new JSONArray(new StringReader(input)); } /** - * Takes a String, parses its contents, and - * returns a JSONArray. If the String - * does not contain JSONArray data or cannot - * be parsed, a null value is returned.
+ * Loads an array of JSON objects from the data folder or a URL, and returns a + * JSONArray. Per standard JSON syntax, the array must be enclosed in a + * pair of hard brackets [], and each object within the array must be + * separated by a comma.
*
- * parseJSONArray() is most useful when pulling - * data dynamically, such as from third-party APIs. - * Normally, API results would be saved to a - * String, and then can be converted to a - * structured JSONArray using parseJSONArray(). - * Be sure to check if null is returned before - * performing operations on the new JSONArray - * in case the String content could not be parsed.
- *
- * If your data already exists as a JSON file in - * the data folder, it is simpler to use loadJSONArray(). + * All files loaded and saved by the Processing API use UTF-8 encoding. + * * @webref input:files - * @webBrief Takes a String, parses its contents, and - * returns a JSONArray. - * @param filename name of a file in the data folder or a URL + * @webBrief Takes a String, parses its contents, and returns a + * JSONArray. + * @param filename + * name of a file in the data folder or a URL * @see JSONArray * @see PApplet#loadJSONObject(String) * @see PApplet#saveJSONObject(JSONObject, String) @@ -5740,22 +5973,22 @@ public class PApplet implements PConstants { /** - * Writes the contents of a JSONArray object to a - * file. By default, this file is saved to the sketch's - * folder. This folder is opened by selecting "Show Sketch Folder" - * from the "Sketch" menu.
+ * Writes the contents of a JSONArray object to a file. By default, + * this file is saved to the sketch's folder. This folder is opened by + * selecting "Show Sketch Folder" from the "Sketch" menu.
*
- * Alternatively, the file can be saved to any location - * on the computer by using an absolute path (something - * that starts with / on Unix and Linux, or a drive letter - * on Windows).
+ * Alternatively, the file can be saved to any location on the computer by + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows).
*
* All files loaded and saved by the Processing API use UTF-8 encoding. + * * @webref output:files - * @webBrief Writes the contents of a JSONArray object to a - * file. - * @param json the JSONArray to save - * @param filename the name of the file to save to + * @webBrief Writes the contents of a JSONArray object to a file. + * @param json + * the JSONArray to save + * @param filename + * the name of the file to save to * @see JSONObject * @see JSONArray * @see PApplet#loadJSONObject(String) @@ -5787,35 +6020,33 @@ public class PApplet implements PConstants { /** - * Reads the contents of a file or URL and creates an - * Table object with its values. If a file is specified, - * it must be located in the sketch's "data" folder. The - * filename parameter can also be a URL to a file found - * online. The filename must either end in an extension - * or an extension must be specified in the options - * parameter. For example, to use tab-separated data, - * include "tsv" in the options parameter if the filename - * or URL does not end in .tsv. Note: If an extension - * is in both places, the extension in the options - * is used.
+ * Reads the contents of a file or URL and creates an Table object with its + * values. If a file is specified, it must be located in the sketch's "data" + * folder. The filename parameter can also be a URL to a file found online. + * The filename must either end in an extension or an extension must be + * specified in the options parameter. For example, to use + * tab-separated data, include "tsv" in the options parameter if the filename + * or URL does not end in .tsv. Note: If an extension is in both + * places, the extension in the options is used.
*
- * If the file contains a header row, include "header" in - * the options parameter. If the file does not have - * a header row, then simply omit the "header" option.
+ * If the file contains a header row, include "header" in the options + * parameter. If the file does not have a header row, then simply omit the + * "header" option.
*
- * Some CSV files contain newline (CR or LF) characters - * inside cells. This is rare, but adding the "newlines" - * option will handle them properly. (This is not enabled - * by default because the parsing code is much slower.)
+ * Some CSV files contain newline (CR or LF) characters inside cells. This is + * rare, but adding the "newlines" option will handle them properly. (This is + * not enabled by default because the parsing code is much slower.)
*
- * When specifying multiple options, separate them with commas, - * as in: loadTable("data.csv", "header, tsv")
+ * When specifying multiple options, separate them with commas, as in: + * loadTable("data.csv", "header, tsv")
*
* All files loaded and saved by the Processing API use UTF-8 encoding. + * * @webref input:files - * @webBrief Reads the contents of a file or URL and creates an - * Table object with its values. - * @param filename name of a file in the data folder or a URL. + * @webBrief Reads the contents of a file or URL and creates an Table object + * with its values. + * @param filename + * name of a file in the data folder or a URL. * @see Table * @see PApplet#saveTable(Table, String) * @see PApplet#loadBytes(String) @@ -5865,18 +6096,22 @@ public class PApplet implements PConstants { /** - * Writes the contents of a Table object to a file. By default, this - * file is saved to the sketch's folder. This folder is opened by - * selecting "Show Sketch Folder" from the "Sketch" menu.
+ * Writes the contents of a Table object to a file. By default, this file is + * saved to the sketch's folder. This folder is opened by selecting "Show + * Sketch Folder" from the "Sketch" menu.
+ *
+ * Alternatively, the file can be saved to any location on the computer by + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows).
*
- * Alternatively, the file can be saved to any location on the computer - * by using an absolute path (something that starts with / on Unix and - * Linux, or a drive letter on Windows).

* All files loaded and saved by the Processing API use UTF-8 encoding. + * * @webref output:files * @webBrief Writes the contents of a Table object to a file. - * @param table the Table object to save to a file - * @param filename the filename to which the Table should be saved + * @param table + * the Table object to save to a file + * @param filename + * the filename to which the Table should be saved * @see Table * @see PApplet#loadTable(String) */ @@ -5920,35 +6155,48 @@ public class PApplet implements PConstants { /** * - * Loads a font into a variable of type PFont. To load correctly, - * fonts must be located in the data directory of the current sketch. To - * create a font to use with Processing, select "Create Font..." from the - * Tools menu. This will create a font in the format Processing requires - * and also adds it to the current sketch's data directory.
+ * Loads a .vlw formatted font into a PFont object. Create a .vlw font + * by selecting "Create Font..." from the Tools menu. This tool creates a + * texture for each alphanumeric character and then adds them as a .vlw file + * to the current sketch's data folder. Because the letters are defined as + * textures (and not vector data) the size at which the fonts are created must + * be considered in relation to the size at which they are drawn. For example, + * load a 32pt font if the sketch displays the font at 32 pixels or smaller. + * Conversely, if a 12pt font is loaded and displayed at 48pts, the letters + * will be distorted because the program will be stretching a small graphic to + * a large size.
*
* Like loadImage() and other functions that load data, the - * loadFont() function should not be used inside draw(), - * because it will slow down the sketch considerably, as the font will be - * re-loaded from the disk (or network) on each frame.
+ * loadFont() function should not be used inside draw(), because + * it will slow down the sketch considerably, as the font will be re-loaded + * from the disk (or network) on each frame. It's recommended to load files + * inside setup()
*
- * For most renderers, Processing displays fonts using the .vlw font - * format, which uses images for each letter, rather than defining them - * through vector data. When hint(ENABLE_NATIVE_FONTS) is used with - * the JAVA2D renderer, the native version of a font will be used if it is - * installed on the user's machine.
+ * To load correctly, fonts must be located in the "data" folder of the + * current sketch. Alternatively, the file maybe be loaded from anywhere on + * the local computer using an absolute path (something that starts with / on + * Unix and Linux, or a drive letter on Windows), or the filename parameter + * can be a URL for a file found on a network.
*
- * Using createFont() (instead of loadFont) enables vector data to - * be used with the JAVA2D (default) renderer setting. This can be helpful - * when many font sizes are needed, or when using any renderer based on - * JAVA2D, such as the PDF library. + * If the file is not available or an error occurs, null will be + * returned and an error message will be printed to the console. The error + * message does not halt the program, however the null value may cause a + * NullPointerException if your code does not check whether the value returned + * is null.
+ *
+ * Use createFont() (instead of loadFont()) to enable vector + * data to be used with the default renderer setting. This can be helpful when + * many font sizes are needed, or when using any renderer based on the default + * renderer, such as the PDF library. * - * @webref typography:loading_displaying - * @webBrief Loads a font into a variable of type PFont. - * @param filename name of the font to load - * @see PFont - * @see PGraphics#textFont(PFont, float) - * @see PApplet#createFont(String, float, boolean, char[]) - */ + * @webref typography:loading_displaying + * @webBrief Loads a font into a variable of type PFont. + * @param filename + * name of the font to load + * @see PFont + * @see PGraphics#textFont(PFont, float) + * @see PApplet#createFont(String, float, boolean, char[]) + */ public PFont loadFont(String filename) { if (!filename.toLowerCase().endsWith(".vlw")) { throw new IllegalArgumentException("loadFont() is for .vlw files, try createFont()"); @@ -5978,45 +6226,44 @@ public class PApplet implements PConstants { /** * - * Dynamically converts a font to the format used by Processing from either - * a font name that's installed on the computer, or from a .ttf or .otf - * file inside the sketches "data" folder. This function is an advanced - * feature for precise control. On most occasions you should create fonts - * through selecting "Create Font..." from the Tools menu. - *

- * Use the PFont.list() method to first determine the names for the - * fonts recognized by the computer and are compatible with this function. - * Because of limitations in Java, not all fonts can be used and some might - * work with one operating system and not others. When sharing a sketch - * with other people or posting it on the web, you may need to include a - * .ttf or .otf version of your font in the data directory of the sketch - * because other people might not have the font installed on their - * computer. Only fonts that can legally be distributed should be included - * with a sketch. - *

+ * Dynamically converts a font to the format used by Processing from a .ttf or + * .otf file inside the sketch's "data" folder or a font that's installed + * elsewhere on the computer. If you want to use a font installed on your + * computer, use the PFont.list() method to first determine the names + * for the fonts recognized by the computer and are compatible with this + * function. Not all fonts can be used and some might work with one operating + * system and not others. When sharing a sketch with other people or posting + * it on the web, you may need to include a .ttf or .otf version of your font + * in the data directory of the sketch because other people might not have the + * font installed on their computer. Only fonts that can legally be + * distributed should be included with a sketch.
+ *
* The size parameter states the font size you want to generate. The - * smooth parameter specifies if the font should be antialiased or - * not, and the charset parameter is an array of chars that - * specifies the characters to generate. - *

- * This function creates a bitmapped version of a font in the same manner - * as the Create Font tool. It loads a font by name, and converts it to a - * series of images based on the size of the font. When possible, the - * text() function will use a native font rather than the bitmapped - * version created behind the scenes with createFont(). For - * instance, when using P2D, the actual native version of the font will be - * employed by the sketch, improving drawing quality and performance. With - * the P3D renderer, the bitmapped version will be used. While this can - * drastically improve speed and appearance, results are poor when - * exporting if the sketch does not include the .otf or .ttf file, and the - * requested font is not available on the machine running the sketch. + * smooth parameter specifies if the font should be antialiased or not. + * The charset parameter is an array of chars that specifies the + * characters to generate.
+ *
+ * This function allows Processing to work with the font natively in the + * default renderer, so the letters are defined by vector geometry and are + * rendered quickly. In the P2D and P3D renderers, the function + * sets the project to render the font as a series of small textures. For + * instance, when using the default renderer, the actual native version of the + * font will be employed by the sketch, improving drawing quality and + * performance. With the P2D and P3D renderers, the bitmapped + * version will be used to improve speed and appearance, but the results are + * poor when exporting if the sketch does not include the .otf or .ttf file, + * and the requested font is not available on the machine running the sketch. * * @webref typography:loading_displaying * @webBrief Dynamically converts a font to the format used by Processing. - * @param name name of the font to load - * @param size point size of the font - * @param smooth true for an antialiased font, false for aliased - * @param charset array containing characters to be generated + * @param name + * name of the font to load + * @param size + * point size of the font + * @param smooth + * true for an antialiased font, false for aliased + * @param charset + * array containing characters to be generated * @see PFont * @see PGraphics#textFont(PFont, float) * @see PGraphics#text(String, float, float, float, float) @@ -6066,9 +6313,9 @@ public class PApplet implements PConstants { /** * Open a platform-specific file chooser dialog to select a file for input. * After the selection is made, the selected File will be passed to the - * 'callback' function. If the dialog is closed or canceled, null will be - * sent to the function, so that the program is not waiting for additional - * input. The callback is necessary because of how threading works. + * 'callback' function. If the dialog is closed or canceled, null will be sent + * to the function, so that the program is not waiting for additional input. + * The callback is necessary because of how threading works. * * 

    * void setup() {
@@ -6085,13 +6332,16 @@ public class PApplet implements PConstants {
    *
* * For advanced users, the method must be 'public', which is true for all - * methods inside a sketch when run from the PDE, but must explicitly be - * set when using Eclipse or other development environments. + * methods inside a sketch when run from the PDE, but must explicitly be set + * when using Eclipse or other development environments. * * @webref input:files - * @webBrief Open a platform-specific file chooser dialog to select a file for input. - * @param prompt message to the user - * @param callback name of the method to be called when the selection is made + * @webBrief Open a platform-specific file chooser dialog to select a file for + * input. + * @param prompt + * message to the user + * @param callback + * name of the method to be called when the selection is made */ public void selectInput(String prompt, String callback) { selectInput(prompt, callback, null); @@ -6126,10 +6376,10 @@ public class PApplet implements PConstants { /** - * Opens a platform-specific file chooser dialog to select a file for output. - * After the selection is made, the selected File will be passed to the - * 'callback' function. If the dialog is closed or canceled, null will be sent - * to the function, so that the program is not waiting for additional input. + * Opens a platform-specific file chooser dialog to select a file for output. + * After the selection is made, the selected File will be passed to the + * 'callback' function. If the dialog is closed or canceled, null will be sent + * to the function, so that the program is not waiting for additional input. * The callback is necessary because of how threading works. * * @webref output:files @@ -6226,15 +6476,15 @@ public class PApplet implements PConstants { /** - * Opens a platform-specific file chooser dialog to select a folder. - * After the selection is made, the selection will be passed to the - * 'callback' function. If the dialog is closed or canceled, null - * will be sent to the function, so that the program is not waiting - * for additional input. The callback is necessary because of how + * Opens a platform-specific file chooser dialog to select a folder. + * After the selection is made, the selection will be passed to the + * 'callback' function. If the dialog is closed or canceled, null + * will be sent to the function, so that the program is not waiting + * for additional input. The callback is necessary because of how * threading works. * * @webref input:files - * @webBrief Opens a platform-specific file chooser dialog to select a folder. + * @webBrief Opens a platform-specific file chooser dialog to select a folder. * @param prompt message to the user * @param callback name of the method to be called when the selection is made */ @@ -6498,18 +6748,22 @@ public class PApplet implements PConstants { /** * * Creates a BufferedReader object that can be used to read files - * line-by-line as individual String objects. This is the complement - * to the createWriter() function. - *

+ * line-by-line as individual String objects. This is the complement to + * the createWriter() function. For more information about the + * BufferedReader class and its methods like readLine() and + * close used in the above example, please consult a Java + * reference.
+ *
* Starting with Processing release 0134, all files loaded and saved by the * Processing API use UTF-8 encoding. In previous releases, the default - * encoding for your platform was used, which causes problems when files - * are moved to other platforms. + * encoding for your platform was used, which causes problems when files are + * moved to other platforms. * * @webref input:files - * @webBrief Creates a BufferedReader object that can be used to read files - * line-by-line as individual String objects. - * @param filename name of the file to be opened + * @webBrief Creates a BufferedReader object that can be used to read + * files line-by-line as individual String objects. + * @param filename + * name of the file to be opened * @see BufferedReader * @see PApplet#createWriter(String) * @see PrintWriter @@ -6582,7 +6836,7 @@ public class PApplet implements PConstants { * encoding for your platform was used, which causes problems when files * are moved to other platforms. * - * + * * @webref output:files * @webBrief reates a new file in the sketch folder, and a PrintWriter object * to write to it. @@ -6667,7 +6921,7 @@ public class PApplet implements PConstants { * In earlier releases, this function was called openStream().
*
* - * + * *

Advanced

* Simplified method to open a Java InputStream. *

@@ -6912,19 +7166,26 @@ public class PApplet implements PConstants { /** * - * Reads the contents of a file or url and places it in a byte array. If a - * file is specified, it must be located in the sketch's "data" - * directory/folder.
+ * Reads the contents of a file and places it in a byte array. If the name of + * the file is used as the parameter, as in the above example, the file must + * be loaded in the sketch's "data" directory/folder.
*
- * The filename parameter can also be a URL to a file found online. For - * security reasons, a Processing sketch found online can only download - * files from the same server from which it came. Getting around this - * restriction requires a signed applet. + * Alternatively, the file maybe be loaded from anywhere on the local computer + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows), or the filename parameter can be a URL for a + * file found on a network.
+ *
+ * If the file is not available or an error occurs, null will be + * returned and an error message will be printed to the console. The error + * message does not halt the program, however the null value may cause a + * NullPointerException if your code does not check whether the value returned + * is null.
* * @webref input:files - * @webBrief Reads the contents of a file or url and places it in a byte array. - * @param filename name of a file in the data folder or a URL. + * @webBrief Reads the contents of a file or url and places it in a byte + * array. + * @param filename + * name of a file in the data folder or a URL. * @see PApplet#loadStrings(String) * @see PApplet#saveStrings(String, String[]) * @see PApplet#saveBytes(String, byte[]) @@ -7122,44 +7383,43 @@ public class PApplet implements PConstants { /** * - * Reads the contents of a file or url and creates a String array of its - * individual lines. If a file is specified, it must be located in the - * sketch's "data" directory/folder.
+ * Reads the contents of a file and creates a String array of its individual + * lines. If the name of the file is used as the parameter, as in the above + * example, the file must be loaded in the sketch's "data" directory/folder. *
- * The filename parameter can also be a URL to a file found online. For - * security reasons, a Processing sketch found online can only download - * files from the same server from which it came. Getting around this - * restriction requires a signed applet. + *
+ * Alternatively, the file maybe be loaded from anywhere on the local computer + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows), or the filename parameter can be a URL for a + * file found on a network.
*
* If the file is not available or an error occurs, null will be * returned and an error message will be printed to the console. The error * message does not halt the program, however the null value may cause a - * NullPointerException if your code does not check whether the value - * returned is null. - *

+ * NullPointerException if your code does not check whether the value returned + * is null.
+ *
* Starting with Processing release 0134, all files loaded and saved by the * Processing API use UTF-8 encoding. In previous releases, the default - * encoding for your platform was used, which causes problems when files - * are moved to other platforms. + * encoding for your platform was used, which causes problems when files are + * moved to other platforms. * - * - *

Advanced

- * Load data from a file and shove it into a String array. + * + *

Advanced

Load data from a file and shove it into a String array. *

- * Exceptions are handled internally, when an error, occurs, an - * exception is printed to the console and 'null' is returned, - * but the program continues running. This is a tradeoff between - * 1) showing the user that there was a problem but 2) not requiring - * that all i/o code is contained in try/catch blocks, for the sake - * of new users (or people who are just trying to get things done - * in a "scripting" fashion. If you want to handle exceptions, - * use Java methods for I/O. + * Exceptions are handled internally, when an error, occurs, an exception is + * printed to the console and 'null' is returned, but the program continues + * running. This is a tradeoff between 1) showing the user that there was a + * problem but 2) not requiring that all i/o code is contained in try/catch + * blocks, for the sake of new users (or people who are just trying to get + * things done in a "scripting" fashion. If you want to handle exceptions, use + * Java methods for I/O. * * @webref input:files - * @webBrief Reads the contents of a file or url and creates a String array of its - * individual lines. - * @param filename name of the file or url to load + * @webBrief Reads the contents of a file or url and creates a String array of + * its individual lines. + * @param filename + * name of the file or url to load * @see PApplet#loadBytes(String) * @see PApplet#saveStrings(String, String[]) * @see PApplet#saveBytes(String, byte[]) @@ -7235,24 +7495,25 @@ public class PApplet implements PConstants { * * Similar to createInput(), this creates a Java OutputStream * for a given filename or path. The file will be created in the sketch - * folder, or in the same folder as an exported application. - *

+ * folder, or in the same folder as an exported application.
+ *
* If the path does not exist, intermediate folders will be created. If an - * exception occurs, it will be printed to the console, and null - * will be returned. - *

- * This function is a convenience over the Java approach that requires you - * to 1) create a FileOutputStream object, 2) determine the exact file - * location, and 3) handle exceptions. Exceptions are handled internally by - * the function, which is more appropriate for "sketch" projects. - *

+ * exception occurs, it will be printed to the console, and null will + * be returned.
+ *
+ * This function is a convenience over the Java approach that requires you to + * 1) create a FileOutputStream object, 2) determine the exact file location, + * and 3) handle exceptions. Exceptions are handled internally by the + * function, which is more appropriate for "sketch" projects.
+ *
* If the output filename ends with .gz, the output will be * automatically GZIP compressed as it is written. * * @webref output:files - * @webBrief Similar to createInput(), this creates a Java OutputStream - * for a given filename or path. - * @param filename name of the file to open + * @webBrief Similar to createInput(), this creates a Java + * OutputStream for a given filename or path. + * @param filename + * name of the file to open * @see PApplet#createInput(String) * @see PApplet#selectOutput(String,String) */ @@ -7285,16 +7546,18 @@ public class PApplet implements PConstants { * basically saveBytes(blah, loadBytes()), but done more efficiently * (and with less confusing syntax).
*
- * When using the targetFile parameter, it writes to a File - * object for greater control over the file location. (Note that unlike - * some other functions, this will not automatically compress or uncompress - * gzip files.) + * The target parameter can be either a String specifying a file name, + * or, for greater control over the file location, a File object. (Note + * that, unlike some other functions, this will not automatically compress or + * uncompress gzip files.) + * * - * * @webref output:files * @webBrief Save the contents of a stream to a file in the sketch folder. - * @param target name of the file to write to - * @param source location to read from (a filename, path, or URL) + * @param target + * name of the file to write to + * @param source + * location to read from (a filename, path, or URL) * @see PApplet#createOutput(String) */ public boolean saveStream(String target, String source) { @@ -7375,24 +7638,21 @@ public class PApplet implements PConstants { /** * - * Opposite of loadBytes(), will write an entire array of bytes to a - * file. The data is saved in binary format. This file is saved to the - * sketch's folder, which is opened by selecting "Show sketch folder" from - * the "Sketch" menu.
- *
- * It is not possible to use saveXxxxx() functions inside a web browser - * unless the sketch is signed applet. To - * save a file back to a server, see the save to - * web code snippet on the Processing Wiki. + * As the opposite of loadBytes(), this function will write an entire + * array of bytes to a file. The data is saved in binary format. This file is + * saved to the sketch's folder, which is opened by selecting "Show Sketch + * Folder" from the "Sketch" menu. Alternatively, the files can be saved to + * any location on the computer by using an absolute path (something that + * starts with / on Unix and Linux, or a drive letter on Windows). + * * - * * @webref output:files - * @webBrief Opposite of loadBytes(), will write an entire array of bytes to a - * file. - * @param filename name of the file to write to - * @param data array of bytes to be written + * @webBrief Opposite of loadBytes(), will write an entire array of + * bytes to a file. + * @param filename + * name of the file to write to + * @param data + * array of bytes to be written * @see PApplet#loadStrings(String) * @see PApplet#loadBytes(String) * @see PApplet#saveStrings(String, String[]) @@ -7493,26 +7753,25 @@ public class PApplet implements PConstants { /** * - * Writes an array of strings to a file, one line per string. This file is - * saved to the sketch's folder, which is opened by selecting "Show sketch - * folder" from the "Sketch" menu.
+ * Writes an array of Strings to a file, one line per String. By default, this + * file is saved to the sketch's folder. This folder is opened by selecting + * "Show Sketch Folder" from the "Sketch" menu.
*
- * It is not possible to use saveXxxxx() functions inside a web browser - * unless the sketch is signed applet. To - * save a file back to a server, see the save to - * web code snippet on the Processing Wiki.
- *
- * Starting with Processing 1.0, all files loaded and saved by the - * Processing API use UTF-8 encoding. In previous releases, the default - * encoding for your platform was used, which causes problems when files - * are moved to other platforms. + * Alternatively, the file can be saved to any location on the computer by + * using an absolute path (something that starts with / on Unix and Linux, or + * a drive letter on Windows).
+ *
+ * Starting with Processing 1.0, all files loaded and saved by the Processing + * API use UTF-8 encoding. In earlier releases, the default encoding for your + * platform was used, which causes problems when files are moved to other + * platforms. * * @webref output:files * @webBrief Writes an array of strings to a file, one line per string. - * @param filename filename for output - * @param data string array to be written + * @param filename + * filename for output + * @param data + * string array to be written * @see PApplet#loadStrings(String) * @see PApplet#loadBytes(String) * @see PApplet#saveBytes(String, byte[]) @@ -7818,18 +8077,19 @@ public class PApplet implements PConstants { /** * - * Sorts an array of numbers from smallest to largest and puts an array of - * words in alphabetical order. The original array is not modified, a - * re-ordered array is returned. The count parameter states the - * number of elements to sort. For example if there are 12 elements in an - * array and if count is the value 5, only the first five elements on the - * array will be sorted. + * Sorts an array of numbers from smallest to largest, or puts an array of + * words in alphabetical order. The original array is not modified; a + * re-ordered array is returned. The count parameter states the number + * of elements to sort. For example, if there are 12 elements in an array and + * count is set to 5, only the first 5 elements in the array will be + * sorted. * * @webref data:array_functions - * @webBrief Sorts an array of numbers from smallest to largest and puts an array of - * words in alphabetical order. - * @param list array to sort + * @webBrief Sorts an array of numbers from smallest to largest and puts an + * array of words in alphabetical order. + * @param list + * array to sort * @see PApplet#reverse(boolean[]) */ static public byte[] sort(byte[] list) { @@ -7901,21 +8161,40 @@ public class PApplet implements PConstants { * * Copies an array (or part of an array) to another array. The src * array is copied to the dst array, beginning at the position - * specified by srcPos and into the position specified by - * dstPos. The number of elements to copy is determined by - * length. The simplified version with two arguments copies an - * entire array to another of the same size. It is equivalent to - * "arrayCopy(src, 0, dst, 0, src.length)". This function is far more - * efficient for copying array data than iterating through a for and - * copying each element. + * specified by srcPosition and into the position specified by + * dstPosition. The number of elements to copy is determined by + * length. Note that copying values overwrites existing values in the + * destination array. To append values instead of overwriting them, use + * concat().
+ *
+ * The simplified version with only two arguments — arrayCopy(src, + * dst) — copies an entire array to another of the same size. It is + * equivalent to arrayCopy(src, 0, dst, 0, src.length).
+ *
+ * Using this function is far more efficient for copying array data than + * iterating through a for() loop and copying each element + * individually. This function only copies references, which means that for + * most purposes it only copies one-dimensional arrays (a single set of + * brackets). If used with a two (or three or more) dimensional array, it will + * only copy the references at the first level, because a two dimensional + * array is simply an "array of arrays". This does not produce an error, + * however, because this is often the desired behavior. Internally, this + * function calls Java's System.arraycopy() + * method, so most things that apply there are inherited. * * @webref data:array_functions * @webBrief Copies an array (or part of an array) to another array. - * @param src the source array - * @param srcPosition starting position in the source array - * @param dst the destination array of the same data type as the source array - * @param dstPosition starting position in the destination array - * @param length number of array elements to be copied + * @param src + * the source array + * @param srcPosition + * starting position in the source array + * @param dst + * the destination array of the same data type as the source array + * @param dstPosition + * starting position in the destination array + * @param length + * number of array elements to be copied * @see PApplet#concat(boolean[], boolean[]) */ static public void arrayCopy(Object src, int srcPosition, @@ -7970,18 +8249,19 @@ public class PApplet implements PConstants { /** * - * Increases the size of an array. By default, this function doubles the - * size of the array, but the optional newSize parameter provides - * precise control over the increase in size. - *

- * When using an array of objects, the data returned from the function must - * be cast to the object array's data type. For example: SomeClass[] - * items = (SomeClass[]) expand(originalArray). + * Increases the size of a one-dimensional array. By default, this function + * doubles the size of the array, but the optional newSize parameter + * provides precise control over the increase in size.
+ *
+ * When using an array of objects, the data returned from the function must be + * cast to the object array's data type. For example: SomeClass[] items = + * (SomeClass[]) expand(originalArray) + * * - * * @webref data:array_functions * @webBrief Increases the size of an array. - * @param list the array to expand + * @param list + * the array to expand * @see PApplet#shorten(boolean[]) */ static public boolean[] expand(boolean[] list) { @@ -8097,7 +8377,7 @@ public class PApplet implements PConstants { * be cast to the object array's data type. For example: SomeClass[] * items = (SomeClass[]) append(originalArray, element). * - * + * * @webref data:array_functions * @webBrief Expands an array by one element and adds data to the new position. * @param array array to append @@ -8151,7 +8431,7 @@ public class PApplet implements PConstants { * be cast to the object array's data type. For example: SomeClass[] * items = (SomeClass[]) shorten(originalArray). * - * + * * @webref data:array_functions * @webBrief Decreases an array by one element and returns the shortened array. * @param list array to shorten @@ -8190,20 +8470,26 @@ public class PApplet implements PConstants { /** * - * Inserts a value or array of values into an existing array. The first two - * parameters must be of the same datatype. The array parameter - * defines the array which will be modified and the second parameter - * defines the data which will be inserted. - *

- * When using an array of objects, the data returned from the function must - * be cast to the object array's data type. For example: SomeClass[] - * items = (SomeClass[]) splice(array1, array2, index). + * Inserts a value or an array of values into an existing array. The first two + * parameters must be arrays of the same datatype. The first parameter + * specifies the initial array to be modified, and the second parameter + * defines the data to be inserted. The third parameter is an index value + * which specifies the array position from which to insert data. (Remember + * that array index numbering starts at zero, so the first position is 0, the + * second position is 1, and so on.)
+ *
+ * When splicing an array of objects, the data returned from the function must + * be cast to the object array's data type. For example: SomeClass[] items + * = (SomeClass[]) splice(array1, array2, index) * * @webref data:array_functions * @webBrief Inserts a value or array of values into an existing array. - * @param list array to splice into - * @param value value to be spliced in - * @param index position in the array from which to insert data + * @param list + * array to splice into + * @param value + * value to be spliced in + * @param index + * position in the array from which to insert data * @see PApplet#concat(boolean[], boolean[]) * @see PApplet#subset(boolean[], int, int) */ @@ -8357,24 +8643,27 @@ public class PApplet implements PConstants { /** - * - * Extracts an array of elements from an existing array. The array - * parameter defines the array from which the elements will be copied and - * the offset and length parameters determine which elements - * to extract. If no length is given, elements will be extracted - * from the offset to the end of the array. When specifying the - * offset remember the first array element is 0. This function does - * not change the source array. - *

- * When using an array of objects, the data returned from the function must - * be cast to the object array's data type. For example: SomeClass[] - * items = (SomeClass[]) subset(originalArray, 0, 4). - * + * + * Extracts an array of elements from an existing array. The list + * parameter defines the array from which the elements will be copied, and the + * start and count parameters specify which elements to extract. + * If no count is given, elements will be extracted from the + * start to the end of the array. When specifying the start, + * remember that the first array element is 0. This function does not change + * the source array.
+ *
+ * When using an array of objects, the data returned from the function must be + * cast to the object array's data type. For example: SomeClass[] items = + * (SomeClass[]) subset(originalArray, 0, 4) + * * @webref data:array_functions * @webBrief Extracts an array of elements from an existing array. - * @param list array to extract from - * @param start position to begin - * @param count number of values to extract + * @param list + * array to extract from + * @param start + * position to begin + * @param count + * number of values to extract * @see PApplet#splice(boolean[], boolean, int) */ static public boolean[] subset(boolean[] list, int start, int count) { @@ -8483,19 +8772,21 @@ public class PApplet implements PConstants { /** - * - * Concatenates two arrays. For example, concatenating the array { 1, 2, 3 - * } and the array { 4, 5, 6 } yields { 1, 2, 3, 4, 5, 6 }. Both parameters - * must be arrays of the same datatype. - *

- * When using an array of objects, the data returned from the function must - * be cast to the object array's data type. For example: SomeClass[] - * items = (SomeClass[]) concat(array1, array2). - * + * + * Concatenates two arrays. For example, concatenating the array { 1, 2, 3 } + * and the array { 4, 5, 6 } yields { 1, 2, 3, 4, 5, 6 }. Both parameters must + * be arrays of the same datatype.
+ *
+ * When using an array of objects, the data returned from the function must be + * cast to the object array's data type. For example: SomeClass[] items = + * (SomeClass[]) concat(array1, array2). + * * @webref data:array_functions - * @webBrief Concatenates two arrays. - * @param a first array to concatenate - * @param b second array to concatenate + * @webBrief Concatenates two arrays. + * @param a + * first array to concatenate + * @param b + * second array to concatenate * @see PApplet#splice(boolean[], boolean, int) * @see PApplet#arrayCopy(Object, int, Object, int, int) */ @@ -8675,7 +8966,7 @@ public class PApplet implements PConstants { * * Combines an array of Strings into one String, each separated by the * character(s) used for the separator parameter. To join arrays of - * ints or floats, it's necessary to first convert them to strings using + * ints or floats, it's necessary to first convert them to Strings using * nf() or nfs(). * * @webref data:string_functions @@ -8710,21 +9001,25 @@ public class PApplet implements PConstants { /** * - * The splitTokens() function splits a String at one or many character - * "tokens." The tokens parameter specifies the character or - * characters to be used as a boundary. - *

- * If no tokens character is specified, any whitespace character is - * used to split. Whitespace characters include tab (\\t), line feed (\\n), - * carriage return (\\r), form feed (\\f), and space. To convert a String - * to an array of integers or floats, use the datatype conversion functions - * int() and float() to convert the array of Strings. + * The splitTokens() function splits a String at one or many character + * delimiters or "tokens." The delim parameter specifies the character + * or characters to be used as a boundary.
+ *
+ * If no delim characters are specified, any whitespace character is + * used to split. Whitespace characters include tab (\t), line feed + * (\n), carriage return (\r), form feed (\f), and space.
+ *
+ * After using this function to parse incoming data, it is common to convert + * the data from Strings to integers or floats by using the datatype + * conversion functions int() and float(). * * @webref data:string_functions - * @webBrief The splitTokens() function splits a String at one or many character - * "tokens." - * @param value the String to be split - * @param delim list of individual characters that will be used as separators + * @webBrief The splitTokens() function splits a String at one or many + * character "tokens." + * @param value + * the String to be split + * @param delim + * list of individual characters that will be used as separators * @see PApplet#split(String, String) * @see PApplet#join(String[], String) * @see PApplet#trim(String) @@ -8743,37 +9038,38 @@ public class PApplet implements PConstants { /** * - * The split() function breaks a string into pieces using a character or - * string as the divider. The delim parameter specifies the + * The split() function breaks a String into pieces using a character + * or string as the delimiter. The delim parameter specifies the * character or characters that mark the boundaries between each piece. A - * String[] array is returned that contains each of the pieces. - *

- * If the result is a set of numbers, you can convert the String[] array to - * to a float[] or int[] array using the datatype conversion functions - * int() and float() (see example above). - *

- * The splitTokens() function works in a similar fashion, except - * that it splits using a range of characters instead of a specific - * character or sequence. - * - * + * expressions as a part of the delim parameter, you'll need to put two + * blackslashes (\\\\) in front of the character (see example above). You can + * read more about + * regular + * expressions and + * escape + * characters on Wikipedia. --> + * * @webref data:string_functions - * @webBrief The split() function breaks a string into pieces using a character or - * string as the divider. + * @webBrief The split() function breaks a string into pieces using a + * character or string as the divider. * @usage web_application - * @param value the String to be split - * @param delim the character or String used to separate the data + * @param value + * the String to be split + * @param delim + * the character or String used to separate the data */ static public String[] split(String value, char delim) { // do this so that the exception occurs inside the user's @@ -8856,33 +9152,37 @@ public class PApplet implements PConstants { /** * - * The match() function is used to apply a regular expression to a piece of - * text, and return matching groups (elements found inside parentheses) as - * a String array. No match will return null. If no groups are specified in - * the regexp, but the sequence matches, an array of length one (with the - * matched text as the first element of the array) will be returned.
+ * This function is used to apply a regular expression to a piece of text, and + * return matching groups (elements found inside parentheses) as a String + * array. If there are no matches, a null value will be returned. If no groups + * are specified in the regular expression, but the sequence matches, an array + * of length 1 (with the matched text as the first element of the array) will + * be returned.
*
* To use the function, first check to see if the result is null. If the - * result is null, then the sequence did not match. If the sequence did - * match, an array is returned. - * If there are groups (specified by sets of parentheses) in the regexp, - * then the contents of each will be returned in the array. - * Element [0] of a regexp match returns the entire matching string, and - * the match groups start at element [1] (the first group is [1], the - * second [2], and so on).
+ * result is null, then the sequence did not match at all. If the sequence did + * match, an array is returned.
*
- * The syntax can be found in the reference for Java's Pattern class. - * For regular expression syntax, read the Java + * If there are groups (specified by sets of parentheses) in the regular + * expression, then the contents of each will be returned in the array. + * Element [0] of a regular expression match returns the entire matching + * string, and the match groups start at element [1] (the first group is [1], + * the second [2], and so on).
+ *
+ * The syntax can be found in the reference for Java's Pattern + * class. For regular expression syntax, read the + * Java * Tutorial on the topic. * * @webref data:string_functions - * @webBrief The match() function is used to apply a regular expression to a piece of - * text, and return matching groups (elements found inside parentheses) as - * a String array. No match will return null. - * @param str the String to be searched - * @param regexp the regexp to be used for matching + * @webBrief The match() function is used to apply a regular expression to a + * piece of text, and return matching groups (elements found inside + * parentheses) as a String array. No match will return null. + * @param str + * the String to be searched + * @param regexp + * the regexp to be used for matching * @see PApplet#matchAll(String, String) * @see PApplet#split(String, String) * @see PApplet#splitTokens(String, String) @@ -8906,33 +9206,37 @@ public class PApplet implements PConstants { /** * - * This function is used to apply a regular expression to a piece of text, - * and return a list of matching groups (elements found inside parentheses) - * as a two-dimensional String array. No matches will return null. If no - * groups are specified in the regexp, but the sequence matches, a two - * dimensional array is still returned, but the second dimension is only of - * length one.
+ * This function is used to apply a regular expression to a piece of text, and + * return a list of matching groups (elements found inside parentheses) as a + * two-dimensional String array. If there are no matches, a null value will be + * returned. If no groups are specified in the regular expression, but the + * sequence matches, a two dimensional array is still returned, but the second + * dimension is only of length one.
*
* To use the function, first check to see if the result is null. If the - * result is null, then the sequence did not match at all. If the sequence - * did match, a 2D array is returned. If there are groups (specified by - * sets of parentheses) in the regexp, then the contents of each will be - * returned in the array. - * Assuming, a loop with counter variable i, element [i][0] of a regexp - * match returns the entire matching string, and the match groups start at - * element [i][1] (the first group is [i][1], the second [i][2], and so - * on).
+ * result is null, then the sequence did not match at all. If the sequence did + * match, a 2D array is returned.
*
- * The syntax can be found in the reference for Java's Pattern class. - * For regular expression syntax, read the Java + * If there are groups (specified by sets of parentheses) in the regular + * expression, then the contents of each will be returned in the array. + * Assuming a loop with counter variable i, element [i][0] of a regular + * expression match returns the entire matching string, and the match groups + * start at element [i][1] (the first group is [i][1], the second [i][2], and + * so on).
+ *
+ * The syntax can be found in the reference for Java's Pattern + * class. For regular expression syntax, read the + * Java * Tutorial on the topic. * * @webref data:string_functions - * @webBrief This function is used to apply a regular expression to a piece of text. - * @param str the String to be searched - * @param regexp the regexp to be used for matching + * @webBrief This function is used to apply a regular expression to a piece of + * text. + * @param str + * the String to be searched + * @param regexp + * the regexp to be used for matching * @see PApplet#match(String, String) * @see PApplet#split(String, String) * @see PApplet#splitTokens(String, String) @@ -9476,23 +9780,27 @@ public class PApplet implements PConstants { /** * * Utility function for formatting numbers into strings. There are two - * versions, one for formatting floats and one for formatting ints. The - * values for the digits, left, and right parameters - * should always be positive integers.

As shown in the above - * example, nf() is used to add zeros to the left and/or right of a - * number. This is typically for aligning a list of numbers. To - * remove digits from a floating-point number, use the - * int(), ceil(), floor(), or round() - * functions. + * versions: one for formatting floats, and one for formatting ints. The + * values for the digits and right parameters should always be + * positive integers. The left parameter should be positive or 0. If it + * is zero, only the right side is formatted.
+ *
+ * As shown in the above example, nf() is used to add zeros to the left + * and/or right of a number. This is typically for aligning a list of numbers. + * To remove digits from a floating-point number, use the + * int(), ceil(), floor(), or round() functions. * * @webref data:string_functions * @webBrief Utility function for formatting numbers into strings. - * @param nums the numbers to format - * @param digits number of digits to pad with zero + * @param nums + * the numbers to format + * @param digits + * number of digits to pad with zero * @see PApplet#nfs(float, int, int) * @see PApplet#nfp(float, int, int) * @see PApplet#nfc(float, int) - * @see int(float) + * @see int(float) */ static public String[] nf(int[] nums, int digits) { @@ -9524,17 +9832,21 @@ public class PApplet implements PConstants { /** * * Utility function for formatting numbers into strings and placing - * appropriate commas to mark units of 1000. There are two versions, one - * for formatting ints and one for formatting an array of ints. The value - * for the digits parameter should always be a positive integer. - *

+ * appropriate commas to mark units of 1000. There are four versions: one for + * formatting ints, one for formatting an array of ints, one for formatting + * floats, and one for formatting an array of floats.
+ *
+ * The value for the right parameter should always be a positive + * integer.
+ *
* For a non-US locale, this will insert periods instead of commas, or * whatever is apprioriate for that region. - * + * * @webref data:string_functions * @webBrief Utility function for formatting numbers into strings and placing - * appropriate commas to mark units of 1000. - * @param nums the numbers to format + * appropriate commas to mark units of 1000. + * @param nums + * the numbers to format * @see PApplet#nf(float, int, int) * @see PApplet#nfp(float, int, int) * @see PApplet#nfs(float, int, int) @@ -9582,9 +9894,9 @@ public class PApplet implements PConstants { * two versions, one for formatting floats and one for formatting ints. The * values for the digits, left, and right parameters * should always be positive integers. - * + * * @webref data:string_functions - * @webBrief Utility function for formatting numbers into strings. + * @webBrief Utility function for formatting numbers into strings. * @param num the number to format * @param digits number of digits to pad with zeroes * @see PApplet#nf(float, int, int) @@ -9614,17 +9926,19 @@ public class PApplet implements PConstants { * in the front when it's negative or positive. */ /** - * - * Utility function for formatting numbers into strings. Similar to - * nf() but puts a "+" in front of positive numbers and a "-" in - * front of negative numbers. There are two versions, one for formatting - * floats and one for formatting ints. The values for the digits, - * left, and right parameters should always be positive integers. - * + * + * Utility function for formatting numbers into strings. Similar to nf() + * but puts a "+" in front of positive numbers and a "-" in front of negative + * numbers. There are two versions: one for formatting floats, and one for + * formatting ints. The values for the digits, left, and + * right parameters should always be positive integers. + * * @webref data:string_functions * @webBrief Utility function for formatting numbers into strings. - * @param num the number to format - * @param digits number of digits to pad with zeroes + * @param num + * the number to format + * @param digits + * number of digits to pad with zeroes * @see PApplet#nf(float, int, int) * @see PApplet#nfs(float, int, int) * @see PApplet#nfc(float, int) @@ -9761,19 +10075,21 @@ public class PApplet implements PConstants { /** * - * Converts a byte, char, int, or color to a String containing the - * equivalent hexadecimal notation. For example color(0, 102, 153) will - * convert to the String "FF006699". This function can help make your geeky - * debugging sessions much happier. - *

- * Note that the maximum number of digits is 8, because an int value can - * only represent up to 32 bits. Specifying more than eight digits will - * simply shorten the string to eight anyway. + * Converts an int, byte, char, or color to a + * String containing the equivalent hexadecimal notation. For example, + * the color value produced by color(0, 102, 153) will convert + * to the String value "FF006699". This function can help make + * your geeky debugging sessions much happier.
+ *
+ * Note that the maximum number of digits is 8, because an int value + * can only represent up to 32 bits. Specifying more than 8 digits will not + * increase the length of the String further. * * @webref data:conversion * @webBrief Converts a byte, char, int, or color to a String containing the - * equivalent hexadecimal notation. - * @param value the value to convert + * equivalent hexadecimal notation. + * @param value + * the value to convert * @see PApplet#unhex(String) * @see PApplet#binary(byte) * @see PApplet#unbinary(String) @@ -9809,19 +10125,20 @@ public class PApplet implements PConstants { } /** - * - * Converts a String representation of a hexadecimal number to its - * equivalent integer value. - * - * - * @webref data:conversion - * @webBrief Converts a String representation of a hexadecimal number to its - * equivalent integer value. - * @param value String to convert to an integer - * @see PApplet#hex(int, int) - * @see PApplet#binary(byte) - * @see PApplet#unbinary(String) - */ + * + * Converts a String representation of a hexadecimal number to its + * equivalent integer value. + * + * + * @webref data:conversion + * @webBrief Converts a String representation of a hexadecimal number to its + * equivalent integer value. + * @param value + * String to convert to an integer + * @see PApplet#hex(int, int) + * @see PApplet#binary(byte) + * @see PApplet#unbinary(String) + */ static final public int unhex(String value) { // has to parse as a Long so that it'll work for numbers bigger than 2^31 return (int) (Long.parseLong(value, 16)); @@ -9861,21 +10178,24 @@ public class PApplet implements PConstants { */ /** - * - * Converts a byte, char, int, or color to a String containing the - * equivalent binary notation. For example color(0, 102, 153, 255) will - * convert to the String "11111111000000000110011010011001". This function - * can help make your geeky debugging sessions much happier. - *

- * Note that the maximum number of digits is 32, because an int value can - * only represent up to 32 bits. Specifying more than 32 digits will simply - * shorten the string to 32 anyway. - * + * + * Converts an int, byte, char, or color to a + * String containing the equivalent binary notation. For example, the + * color value produced by color(0, 102, 153, 255) will convert + * to the String value "11111111000000000110011010011001". This + * function can help make your geeky debugging sessions much happier.
+ *
+ * Note that the maximum number of digits is 32, because an int value + * can only represent up to 32 bits. Specifying more than 32 digits will have + * no effect. + * * @webref data:conversion * @webBrief Converts a byte, char, int, or color to a String containing the - * equivalent binary notation. - * @param value value to convert - * @param digits number of digits to return + * equivalent binary notation. + * @param value + * value to convert + * @param digits + * number of digits to return * @see PApplet#unbinary(String) * @see PApplet#hex(int,int) * @see PApplet#unhex(String) @@ -9899,18 +10219,20 @@ public class PApplet implements PConstants { /** - * - * Converts a String representation of a binary number to its equivalent - * integer value. For example, unbinary("00001000") will return 8. - * - * @webref data:conversion - * @webBrief Converts a String representation of a binary number to its equivalent - * integer value. - * @param value String to convert to an integer - * @see PApplet#binary(byte) - * @see PApplet#hex(int,int) - * @see PApplet#unhex(String) - */ + * + * Converts a String representation of a binary number to its equivalent + * integer value. For example, unbinary("00001000") will return + * 8. + * + * @webref data:conversion + * @webBrief Converts a String representation of a binary number to its + * equivalent integer value. + * @param value + * String to convert to an integer + * @see PApplet#binary(byte) + * @see PApplet#hex(int,int) + * @see PApplet#unhex(String) + */ static final public int unbinary(String value) { return Integer.parseInt(value, 2); } @@ -9927,16 +10249,29 @@ public class PApplet implements PConstants { /** * - * Creates colors for storing in variables of the color datatype. - * The parameters are interpreted as RGB or HSB values depending on the - * current colorMode(). The default mode is RGB values from 0 to 255 - * and therefore, the function call color(255, 204, 0) will return a - * bright yellow color. More about how colors are stored can be found in - * the reference for the color datatype. + * Creates colors for storing in variables of the color datatype. The + * parameters are interpreted as RGB or HSB values depending on the current + * colorMode(). The default mode is RGB values from 0 to 255 and, + * therefore, color(255, 204, 0) will return a bright yellow color (see + * the first example above).
+ *
+ * Note that if only one value is provided to color(), it will be + * interpreted as a grayscale value. Add a second value, and it will be used + * for alpha transparency. When three values are specified, they are + * interpreted as either RGB or HSB values. Adding a fourth value applies + * alpha transparency.
+ *
+ * Note that when using hexadecimal notation, it is not necessary to use + * color(), as in: color c = #006699
+ *
+ * More about how colors are stored can be found in the reference for the + * color datatype. * * @webref color:creating_reading - * @webBrief Creates colors for storing in variables of the color datatype. - * @param gray number specifying value between white and black + * @webBrief Creates colors for storing in variables of the color + * datatype. + * @param gray + * number specifying value between white and black * @see PApplet#colorMode(int) */ public final int color(int gray) { @@ -10053,18 +10388,26 @@ public class PApplet implements PConstants { /** * - * Calculates a color or colors between two color at a specific increment. - * The amt parameter is the amount to interpolate between the two - * values where 0.0 equal to the first point, 0.1 is very near the first - * point, 0.5 is half-way in between, etc. + * Calculates a color between two colors at a specific increment. The + * amt parameter is the amount to interpolate between the two values + * where 0.0 is equal to the first point, 0.1 is very near the first point, + * 0.5 is halfway in between, etc.
+ * An amount below 0 will be treated as 0. Likewise, amounts above 1 will be + * capped at 1. This is different from the behavior of lerp(), but necessary + * because otherwise numbers outside the range will produce strange and + * unexpected colors. + * * - * * @webref color:creating_reading - * @webBrief Calculates a color or colors between two color at a specific increment. + * @webBrief Calculates a color or colors between two color at a specific + * increment. * @usage web_application - * @param c1 interpolate from this color - * @param c2 interpolate to this color - * @param amt between 0.0 and 1.0 + * @param c1 + * interpolate from this color + * @param c2 + * interpolate to this color + * @param amt + * between 0.0 and 1.0 * @see PImage#blendColor(int, int, int) * @see PGraphics#color(float, float, float, float) * @see PApplet#lerp(float, float, float) @@ -10598,20 +10941,24 @@ public class PApplet implements PConstants { * Opens a new file and all subsequent drawing functions are echoed to this * file as well as the display window. The beginRecord() function * requires two parameters, the first is the renderer and the second is the - * file name. This function is always used with endRecord() to stop - * the recording process and close the file. - *

- * Note that beginRecord() will only pick up any settings that happen after - * it has been called. For instance, if you call textFont() before - * beginRecord(), then that font will not be set for the file that you're - * recording to. + * file name. This function is always used with endRecord() to stop the + * recording process and close the file.
+ *
+ * Note that beginRecord() will only pick up any settings that happen + * after it has been called. For instance, if you call textFont() + * before beginRecord(), then that font will not be set for the file + * that you're recording to.
+ *
+ * beginRecord() works only with the PDF and SVG renderers. + * * - * * @webref output:files - * @webBrief Opens a new file and all subsequent drawing functions are echoed to this - * file as well as the display window. - * @param renderer PDF or SVG - * @param filename filename for output + * @webBrief Opens a new file and all subsequent drawing functions are echoed + * to this file as well as the display window. + * @param renderer + * PDF or SVG + * @param filename + * filename for output * @see PApplet#endRecord() */ public PGraphics beginRecord(String renderer, String filename) { @@ -10679,7 +11026,7 @@ public class PApplet implements PConstants { * See examples in the reference for the PDF and DXF * libraries for more information. * - * + * * @webref output:files * @webBrief To create vectors from 3D data, use the beginRaw() and * endRaw() commands. @@ -10717,7 +11064,7 @@ public class PApplet implements PConstants { * Complement to beginRaw(); they must always be used together. See * the beginRaw() reference for details. * - * + * * @webref output:files * @webBrief Complement to beginRaw(); they must always be used together. * @see PApplet#beginRaw(String, String) @@ -10742,25 +11089,18 @@ public class PApplet implements PConstants { /** * - * Loads the pixel data for the display window into the pixels[] - * array. This function must always be called before reading from or - * writing to pixels[]. - *

renderers may or may not seem to require loadPixels() - * or updatePixels(). However, the rule is that any time you want to - * manipulate the pixels[] array, you must first call - * loadPixels(), and after changes have been made, call - * updatePixels(). Even if the renderer may not seem to use this - * function in the current Processing release, this will always be subject - * to change. + * Loads the pixel data of the current display window into the pixels[] + * array. This function must always be called before reading from or writing + * to pixels[]. Subsequent changes to the display window will not be + * reflected in pixels until loadPixels() is called again. * - *

Advanced

- * Override the g.pixels[] function to set the pixels[] array - * that's part of the PApplet object. Allows the use of - * pixels[] in the code, rather than g.pixels[]. + *

Advanced

Override the g.pixels[] function to set the pixels[] + * array that's part of the PApplet object. Allows the use of pixels[] in the + * code, rather than g.pixels[]. * * @webref image:pixels - * @webBrief Loads the pixel data for the display window into the pixels[] - * array. + * @webBrief Loads the pixel data for the display window into the + * pixels[] array. * @see PApplet#pixels * @see PApplet#updatePixels() */ @@ -10770,27 +11110,18 @@ public class PApplet implements PConstants { } /** - * - * Updates the display window with the data in the pixels[] array. - * Use in conjunction with loadPixels(). If you're only reading - * pixels from the array, there's no need to call updatePixels() - * unless there are changes. - *

renderers may or may not seem to require loadPixels() - * or updatePixels(). However, the rule is that any time you want to - * manipulate the pixels[] array, you must first call - * loadPixels(), and after changes have been made, call - * updatePixels(). Even if the renderer may not seem to use this - * function in the current Processing release, this will always be subject - * to change. - *

- * Currently, none of the renderers use the additional parameters to - * updatePixels(), however this may be implemented in the future. - * - * @webref image:pixels - * @webBrief Updates the display window with the data in the pixels[] array. - * @see PApplet#loadPixels() - * @see PApplet#pixels - */ + * + * Updates the display window with the data in the pixels[] array. Use + * in conjunction with loadPixels(). If you're only reading pixels from + * the array, there's no need to call updatePixels() — updating is + * only necessary to apply changes. + * + * @webref image:pixels + * @webBrief Updates the display window with the data in the pixels[] + * array. + * @see PApplet#loadPixels() + * @see PApplet#pixels + */ public void updatePixels() { g.updatePixels(); } @@ -10848,43 +11179,44 @@ public class PApplet implements PConstants { } - /** - * - * Using the beginShape() and endShape() functions allow - * creating more complex forms. beginShape() begins recording - * vertices for a shape and endShape() stops recording. The value of - * the MODE parameter tells it which types of shapes to create from - * the provided vertices. With no mode specified, the shape can be any - * irregular polygon. The parameters available for beginShape() are POINTS, - * LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, QUADS, and QUAD_STRIP. - * After calling the beginShape() function, a series of - * vertex() commands must follow. To stop drawing the shape, call - * endShape(). The vertex() function with two parameters - * specifies a position in 2D and the vertex() function with three - * parameters specifies a position in 3D. Each shape will be outlined with - * the current stroke color and filled with the fill color. - *

- * Transformations such as translate(), rotate(), and - * scale() do not work within beginShape(). It is also not - * possible to use other shapes, such as ellipse() or rect() - * within beginShape(). - *

- * The P3D renderer settings allow stroke() and fill() - * settings to be altered per-vertex, however the default P2D renderer does - * not. Settings such as strokeWeight(), strokeCap(), and - * strokeJoin() cannot be changed while inside a - * beginShape()/endShape() block with any renderer. - * - * @webref shape:vertex - * @webBrief Using the beginShape() and endShape() functions allow - * creating more complex forms. - * @param kind Either POINTS, LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, QUADS, or QUAD_STRIP - * @see PShape - * @see PGraphics#endShape() - * @see PGraphics#vertex(float, float, float, float, float) - * @see PGraphics#curveVertex(float, float, float) - * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, float, float) - */ + /** + * + * Using the beginShape() and endShape() functions allow creating + * more complex forms. beginShape() begins recording vertices for a shape + * and endShape() stops recording. The value of the kind parameter + * tells it which types of shapes to create from the provided vertices. With no + * mode specified, the shape can be any irregular polygon. The parameters + * available for beginShape() are POINTS, LINES, TRIANGLES, TRIANGLE_FAN, + * TRIANGLE_STRIP, QUADS, and QUAD_STRIP. After calling the beginShape() + * function, a series of vertex() commands must follow. To stop drawing + * the shape, call endShape(). The vertex() function with two + * parameters specifies a position in 2D and the vertex() function with + * three parameters specifies a position in 3D. Each shape will be outlined with + * the current stroke color and filled with the fill color.
+ *
+ * Transformations such as translate(), rotate(), and + * scale() do not work within beginShape(). It is also not + * possible to use other shapes, such as ellipse() or rect() + * within beginShape().
+ *
+ * The P2D and P3D renderers allow stroke() and fill() to be + * altered on a per-vertex basis, but the default renderer does not. Settings + * such as strokeWeight(), strokeCap(), and strokeJoin() + * cannot be changed while inside a beginShape()/endShape() block + * with any renderer. + * + * @webref shape:vertex + * @webBrief Using the beginShape() and endShape() functions allow + * creating more complex forms. + * @param kind Either POINTS, LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, + * QUADS, or QUAD_STRIP + * @see PShape + * @see PGraphics#endShape() + * @see PGraphics#vertex(float, float, float, float, float) + * @see PGraphics#curveVertex(float, float, float) + * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, + * float, float) + */ public void beginShape(int kind) { if (recorder != null) recorder.beginShape(kind); g.beginShape(kind); @@ -10901,24 +11233,24 @@ public class PApplet implements PConstants { } - /** - * - * Sets the current normal vector. This is for drawing three dimensional - * shapes and surfaces and specifies a vector perpendicular to the surface - * of the shape which determines how lighting affects it. Processing - * attempts to automatically assign normals to shapes, but since that's - * imperfect, this is a better option when you want more control. This - * function is identical to glNormal3f() in OpenGL. - * - * @webref lights_camera:lights - * @webBrief Sets the current normal vector. - * @param nx x direction - * @param ny y direction - * @param nz z direction - * @see PGraphics#beginShape(int) - * @see PGraphics#endShape(int) - * @see PGraphics#lights() - */ + /** + * + * Sets the current normal vector. Used for drawing three dimensional shapes and + * surfaces, normal() specifies a vector perpendicular to a shape's + * surface which, in turn, determines how lighting affects it. Processing + * attempts to automatically assign normals to shapes, but since that's + * imperfect, this is a better option when you want more control. This function + * is identical to glNormal3f() in OpenGL. + * + * @webref lights_camera:lights + * @webBrief Sets the current normal vector. + * @param nx x direction + * @param ny y direction + * @param nz z direction + * @see PGraphics#beginShape(int) + * @see PGraphics#endShape(int) + * @see PGraphics#lights() + */ public void normal(float nx, float ny, float nz) { if (recorder != null) recorder.normal(nx, ny, nz); g.normal(nx, ny, nz); @@ -10961,22 +11293,23 @@ public class PApplet implements PConstants { } - /** - * - * Sets the coordinate space for texture mapping. There are two options, - * IMAGE, which refers to the actual coordinates of the image, and - * NORMAL, which refers to a normalized space of values ranging from 0 - * to 1. The default mode is IMAGE. In IMAGE, if an image is 100 x 200 - * pixels, mapping the image onto the entire size of a quad would require - * the points (0,0) (0,100) (100,200) (0,200). The same mapping in - * NORMAL_SPACE is (0,0) (0,1) (1,1) (0,1). - * - * @webref image:textures - * @webBrief Sets the coordinate space for texture mapping. - * @param mode either IMAGE or NORMAL - * @see PGraphics#texture(PImage) - * @see PGraphics#textureWrap(int) - */ + /** + * + * Sets the coordinate space for texture mapping. The default mode is + * IMAGE, which refers to the actual coordinates of the image. + * NORMAL refers to a normalized space of values ranging from 0 to 1. + * This function only works with the P2D and P3D renderers.
+ *
+ * With IMAGE, if an image is 100 x 200 pixels, mapping the image onto + * the entire size of a quad would require the points (0,0) (100, 0) (100,200) + * (0,200). The same mapping in NORMAL is (0,0) (1,0) (1,1) (0,1). + * + * @webref image:textures + * @webBrief Sets the coordinate space for texture mapping. + * @param mode either IMAGE or NORMAL + * @see PGraphics#texture(PImage) + * @see PGraphics#textureWrap(int) + */ public void textureMode(int mode) { if (recorder != null) recorder.textureMode(mode); g.textureMode(mode); @@ -11002,24 +11335,26 @@ public class PApplet implements PConstants { } - /** - * - * Sets a texture to be applied to vertex points. The texture() - * function must be called between beginShape() and - * endShape() and before any calls to vertex(). - *

- * When textures are in use, the fill color is ignored. Instead, use tint() - * to specify the color of the texture as it is applied to the shape. - * - * @webref image:textures - * @webBrief Sets a texture to be applied to vertex points. - * @param image reference to a PImage object - * @see PGraphics#textureMode(int) - * @see PGraphics#textureWrap(int) - * @see PGraphics#beginShape(int) - * @see PGraphics#endShape(int) - * @see PGraphics#vertex(float, float, float, float, float) - */ + /** + * + * Sets a texture to be applied to vertex points. The texture() function + * must be called between beginShape() and endShape() and before + * any calls to vertex(). This function only works with the P2D and P3D + * renderers.
+ *
+ * When textures are in use, the fill color is ignored. Instead, use + * tint() to specify the color of the texture as it is applied to the + * shape. + * + * @webref image:textures + * @webBrief Sets a texture to be applied to vertex points. + * @param image reference to a PImage object + * @see PGraphics#textureMode(int) + * @see PGraphics#textureWrap(int) + * @see PGraphics#beginShape(int) + * @see PGraphics#endShape(int) + * @see PGraphics#vertex(float, float, float, float, float) + */ public void texture(PImage image) { if (recorder != null) recorder.texture(image); g.texture(image); @@ -11067,22 +11402,22 @@ public class PApplet implements PConstants { /** - * - * All shapes are constructed by connecting a series of vertices. - * vertex() is used to specify the vertex coordinates for points, - * lines, triangles, quads, and polygons and is used exclusively within the - * beginShape() and endShape() function.
- *
- * Drawing a vertex in 3D using the z parameter requires the P3D - * parameter in combination with size as shown in the above example.
- *
- * This function is also used to map a texture onto the geometry. The - * texture() function declares the texture to apply to the geometry - * and the u and v coordinates set define the mapping of this - * texture to the form. By default, the coordinates used for u and - * v are specified in relation to the image's size in pixels, but - * this relation can be changed with textureMode(). - * + * + * All shapes are constructed by connecting a series of vertices. + * vertex() is used to specify the vertex coordinates for points, lines, + * triangles, quads, and polygons. It is used exclusively within the + * beginShape() and endShape() functions.
+ *
+ * Drawing a vertex in 3D using the z parameter requires the P3D + * parameter in combination with size, as shown in the above example.
+ *
+ * This function is also used to map a texture onto geometry. The + * texture() function declares the texture to apply to the geometry and + * the u and v coordinates set define the mapping of this texture + * to the form. By default, the coordinates used for u and v are + * specified in relation to the image's size in pixels, but this relation can be + * changed with textureMode(). + * * @webref shape:vertex * @webBrief All shapes are constructed by connecting a series of vertices. * @param x x-coordinate of the vertex @@ -11092,7 +11427,8 @@ public class PApplet implements PConstants { * @param v vertical coordinate for the texture mapping * @see PGraphics#beginShape(int) * @see PGraphics#endShape(int) - * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, float, float) + * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, + * float, float) * @see PGraphics#quadraticVertex(float, float, float, float, float, float) * @see PGraphics#curveVertex(float, float, float) * @see PGraphics#texture(PImage) @@ -11569,22 +11905,33 @@ public class PApplet implements PConstants { } - /** - * - * Draws a point, a coordinate in space at the dimension of one pixel. The - * first parameter is the horizontal value for the point, the second value - * is the vertical value for the point, and the optional third value is the - * depth value. Drawing this shape in 3D with the z parameter - * requires the P3D parameter in combination with size() as shown in - * the above example. - * - * - * @webref shape:2d_primitives - * @webBrief Draws a point, a coordinate in space at the dimension of one pixel. - * @param x x-coordinate of the point - * @param y y-coordinate of the point - * @see PGraphics#stroke(int) - */ + /** + * + * Draws a point, a coordinate in space at the dimension of one pixel. The first + * parameter is the horizontal value for the point, the second value is the + * vertical value for the point, and the optional third value is the depth + * value. Drawing this shape in 3D with the z parameter requires the P3D + * parameter in combination with size() as shown in the above example. + *
+ *
+ * Use stroke() to set the color of a point().
+ *
+ * Point appears round with the default strokeCap(ROUND) and square with + * strokeCap(PROJECT). Points are invisible with strokeCap(SQUARE) + * (no cap).
+ *
+ * Using point() with strokeWeight(1) or smaller may draw nothing to the screen, + * depending on the graphics settings of the computer. Workarounds include + * setting the pixel using set() or drawing the point using either + * circle() or square(). + * + * + * @webref shape:2d_primitives + * @webBrief Draws a point, a coordinate in space at the dimension of one pixel. + * @param x x-coordinate of the point + * @param y y-coordinate of the point + * @see PGraphics#stroke(int) + */ public void point(float x, float y) { if (recorder != null) recorder.point(x, y); g.point(x, y); @@ -11689,53 +12036,67 @@ public class PApplet implements PConstants { } - /** - * - * Modifies the location from which rectangles draw. The default mode is - * rectMode(CORNER), which specifies the location to be the upper - * left corner of the shape and uses the third and fourth parameters of - * rect() to specify the width and height. The syntax - * rectMode(CORNERS) uses the first and second parameters of - * rect() to set the location of one corner and uses the third and - * fourth parameters to set the opposite corner. The syntax - * rectMode(CENTER) draws the image from its center point and uses - * the third and forth parameters of rect() to specify the image's - * width and height. The syntax rectMode(RADIUS) draws the image - * from its center point and uses the third and forth parameters of - * rect() to specify half of the image's width and height. The - * parameter must be written in ALL CAPS because Processing is a case - * sensitive language. Note: In version 125, the mode named CENTER_RADIUS - * was shortened to RADIUS. - * - * @webref shape:attributes - * @webBrief Modifies the location from which rectangles draw. - * @param mode either CORNER, CORNERS, CENTER, or RADIUS - * @see PGraphics#rect(float, float, float, float) - */ + /** + * + * Modifies the location from which rectangles are drawn by changing the way in + * which parameters given to rect() are intepreted.
+ *
+ * The default mode is rectMode(CORNER), which interprets the first two + * parameters of rect() as the upper-left corner of the shape, while the + * third and fourth parameters are its width and height.
+ *
+ * rectMode(CORNERS) interprets the first two parameters of rect() + * as the location of one corner, and the third and fourth parameters as the + * location of the opposite corner.
+ *
+ * rectMode(CENTER) interprets the first two parameters of rect() + * as the shape's center point, while the third and fourth parameters are its + * width and height.
+ *
+ * rectMode(RADIUS) also uses the first two parameters of rect() + * as the shape's center point, but uses the third and fourth parameters to + * specify half of the shapes's width and height.
+ *
+ * The parameter must be written in ALL CAPS because Processing is a + * case-sensitive language. + * + * @webref shape:attributes + * @webBrief Modifies the location from which rectangles draw. + * @param mode either CORNER, CORNERS, CENTER, or RADIUS + * @see PGraphics#rect(float, float, float, float) + */ public void rectMode(int mode) { if (recorder != null) recorder.rectMode(mode); g.rectMode(mode); } - /** - * - * Draws a rectangle to the screen. A rectangle is a four-sided shape with - * every angle at ninety degrees. By default, the first two parameters set - * the location of the upper-left corner, the third sets the width, and the - * fourth sets the height. These parameters may be changed with the - * rectMode() function. - * - * - * @webref shape:2d_primitives - * @webBrief Draws a rectangle to the screen. - * @param a x-coordinate of the rectangle by default - * @param b y-coordinate of the rectangle by default - * @param c width of the rectangle by default - * @param d height of the rectangle by default - * @see PGraphics#rectMode(int) - * @see PGraphics#quad(float, float, float, float, float, float, float, float) - */ + /** + * + * Draws a rectangle to the screen. A rectangle is a four-sided shape with every + * angle at ninety degrees. By default, the first two parameters set the + * location of the upper-left corner, the third sets the width, and the fourth + * sets the height. The way these parameters are interpreted, however, may be + * changed with the rectMode() function.
+ *
+ * To draw a rounded rectangle, add a fifth parameter, which is used as the + * radius value for all four corners.
+ *
+ * To use a different radius value for each corner, include eight parameters. + * When using eight parameters, the latter four set the radius of the arc at + * each corner separately, starting with the top-left corner and moving + * clockwise around the rectangle. + * + * + * @webref shape:2d_primitives + * @webBrief Draws a rectangle to the screen. + * @param a x-coordinate of the rectangle by default + * @param b y-coordinate of the rectangle by default + * @param c width of the rectangle by default + * @param d height of the rectangle by default + * @see PGraphics#rectMode(int) + * @see PGraphics#quad(float, float, float, float, float, float, float, float) + */ public void rect(float a, float b, float c, float d) { if (recorder != null) recorder.rect(a, b, c, d); g.rect(a, b, c, d); @@ -11788,75 +12149,98 @@ public class PApplet implements PConstants { } - /** - * - * The origin of the ellipse is modified by the ellipseMode() - * function. The default configuration is ellipseMode(CENTER), which - * specifies the location of the ellipse as the center of the shape. The - * RADIUS mode is the same, but the width and height parameters to - * ellipse() specify the radius of the ellipse, rather than the - * diameter. The CORNER mode draws the shape from the upper-left - * corner of its bounding box. The CORNERS mode uses the four - * parameters to ellipse() to set two opposing corners of the - * ellipse's bounding box. The parameter must be written in ALL CAPS - * because Processing is a case-sensitive language. - * - * @webref shape:attributes - * @webBrief The origin of the ellipse is modified by the ellipseMode() - * function. - * @param mode either CENTER, RADIUS, CORNER, or CORNERS - * @see PApplet#ellipse(float, float, float, float) - * @see PApplet#arc(float, float, float, float, float, float) - */ + /** + * + * Modifies the location from which ellipses are drawn by changing the way in + * which parameters given to ellipse() are intepreted.
+ *
+ * The default mode is ellipseMode(CENTER), which interprets the first + * two parameters of ellipse() as the shape's center point, while the + * third and fourth parameters are its width and height.
+ *
+ * ellipseMode(RADIUS) also uses the first two parameters of + * ellipse() as the shape's center point, but uses the third and fourth + * parameters to specify half of the shapes's width and height.
+ *
+ * ellipseMode(CORNER) interprets the first two parameters of + * ellipse() as the upper-left corner of the shape, while the third and + * fourth parameters are its width and height.
+ *
+ * ellipseMode(CORNERS) interprets the first two parameters of + * ellipse() as the location of one corner of the ellipse's bounding box, + * and the third and fourth parameters as the location of the opposite + * corner.
+ *
+ * The parameter must be written in ALL CAPS because Processing is a + * case-sensitive language. + * + * @webref shape:attributes + * @webBrief The origin of the ellipse is modified by the ellipseMode() + * function. + * @param mode either CENTER, RADIUS, CORNER, or CORNERS + * @see PApplet#ellipse(float, float, float, float) + * @see PApplet#arc(float, float, float, float, float, float) + */ public void ellipseMode(int mode) { if (recorder != null) recorder.ellipseMode(mode); g.ellipseMode(mode); } - /** - * - * Draws an ellipse (oval) in the display window. An ellipse with an equal - * width and height is a circle. The first two parameters set - * the location, the third sets the width, and the fourth sets the height. - * The origin may be changed with the ellipseMode() function. - * - * @webref shape:2d_primitives - * @webBrief Draws an ellipse (oval) in the display window. - * @param a x-coordinate of the ellipse - * @param b y-coordinate of the ellipse - * @param c width of the ellipse by default - * @param d height of the ellipse by default - * @see PApplet#ellipseMode(int) - * @see PApplet#arc(float, float, float, float, float, float) - */ + /** + * + * Draws an ellipse (oval) to the screen. An ellipse with equal width and height + * is a circle. By default, the first two parameters set the location, and the + * third and fourth parameters set the shape's width and height. The origin may + * be changed with the ellipseMode() function. + * + * @webref shape:2d_primitives + * @webBrief Draws an ellipse (oval) in the display window. + * @param a x-coordinate of the ellipse + * @param b y-coordinate of the ellipse + * @param c width of the ellipse by default + * @param d height of the ellipse by default + * @see PApplet#ellipseMode(int) + * @see PApplet#arc(float, float, float, float, float, float) + */ public void ellipse(float a, float b, float c, float d) { if (recorder != null) recorder.ellipse(a, b, c, d); g.ellipse(a, b, c, d); } - /** - * - * Draws an arc in the display window. Arcs are drawn along the outer edge - * of an ellipse defined by the x, y, width and - * height parameters. The origin or the arc's ellipse may be changed - * with the ellipseMode() function. The start and stop - * parameters specify the angles at which to draw the arc. - * - * @webref shape:2d_primitives - * @webBrief Draws an arc in the display window. - * @param a x-coordinate of the arc's ellipse - * @param b y-coordinate of the arc's ellipse - * @param c width of the arc's ellipse by default - * @param d height of the arc's ellipse by default - * @param start angle to start the arc, specified in radians - * @param stop angle to stop the arc, specified in radians - * @see PApplet#ellipse(float, float, float, float) - * @see PApplet#ellipseMode(int) - * @see PApplet#radians(float) - * @see PApplet#degrees(float) - */ + /** + * + * Draws an arc to the screen. Arcs are drawn along the outer edge of an ellipse + * defined by the a, b, c, and d parameters. The + * origin of the arc's ellipse may be changed with the ellipseMode() + * function. Use the start and stop parameters to specify the + * angles (in radians) at which to draw the arc. The start/stop values must be + * in clockwise order.
+ *
+ * There are three ways to draw an arc; the rendering technique used is defined + * by the optional seventh parameter. The three options, depicted in the above + * examples, are PIE, OPEN, and CHORD. The default mode is the OPEN stroke with + * a PIE fill.
+ *
+ * In some cases, the arc() function isn't accurate enough for smooth + * drawing. For example, the shape may jitter on screen when rotating slowly. If + * you're having an issue with how arcs are rendered, you'll need to draw the + * arc yourself with beginShape()/endShape() or a PShape. + * + * @webref shape:2d_primitives + * @webBrief Draws an arc in the display window. + * @param a x-coordinate of the arc's ellipse + * @param b y-coordinate of the arc's ellipse + * @param c width of the arc's ellipse by default + * @param d height of the arc's ellipse by default + * @param start angle to start the arc, specified in radians + * @param stop angle to stop the arc, specified in radians + * @see PApplet#ellipse(float, float, float, float) + * @see PApplet#ellipseMode(int) + * @see PApplet#radians(float) + * @see PApplet#degrees(float) + */ public void arc(float a, float b, float c, float d, float start, float stop) { if (recorder != null) recorder.arc(a, b, c, d, start, stop); @@ -12074,20 +12458,21 @@ public class PApplet implements PConstants { } - /** - * - * Sets the resolution at which Beziers display. The default value is 20. - * This function is only useful when using the P3D renderer as the default - * P2D renderer does not use this information. - * - * - * @webref shape:curves - * @webBrief Sets the resolution at which Beziers display. - * @param detail resolution of the curves - * @see PGraphics#curve(float, float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#curveVertex(float, float, float) - * @see PGraphics#curveTightness(float) - */ + /** + * + * Sets the resolution at which Beziers display. The default value is 20. This + * function is only useful when using the P3D renderer; the default + * P2D renderer does not use this information. + * + * + * @webref shape:curves + * @webBrief Sets the resolution at which Beziers display. + * @param detail resolution of the curves + * @see PGraphics#curve(float, float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#curveVertex(float, float, float) + * @see PGraphics#curveTightness(float) + */ public void bezierDetail(int detail) { if (recorder != null) recorder.bezierDetail(detail); g.bezierDetail(detail); @@ -12164,25 +12549,29 @@ public class PApplet implements PConstants { } - /** - * - * Evalutes the curve at point t for points a, b, c, d. The parameter t - * varies between 0 and 1, a and d are the control points, and b and c are - * the points on the curve. This can be done once with the x coordinates and a - * second time with the y coordinates to get the location of a curve at t. - * - * - * @webref shape:curves - * @webBrief Evalutes the curve at point t for points a, b, c, d. - * @param a coordinate of first control point - * @param b coordinate of first point on the curve - * @param c coordinate of second point on the curve - * @param d coordinate of second control point - * @param t value between 0 and 1 - * @see PGraphics#curve(float, float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#curveVertex(float, float) - * @see PGraphics#bezierPoint(float, float, float, float, float) - */ + /** + * + * Evaluates the curve at point t for points a, b, + * c, d. The parameter t may range from 0 (the start of the + * curve) and 1 (the end of the curve). a and d are the control + * points, and b and c are points on the curve. As seen in the + * example above, this can be used once with the x coordinates and a + * second time with the y coordinates to get the location of a curve at + * t. + * + * + * @webref shape:curves + * @webBrief Evalutes the curve at point t for points a, b, c, d. + * @param a coordinate of first control point + * @param b coordinate of first point on the curve + * @param c coordinate of second point on the curve + * @param d coordinate of second control point + * @param t value between 0 and 1 + * @see PGraphics#curve(float, float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#curveVertex(float, float) + * @see PGraphics#bezierPoint(float, float, float, float, float) + */ public float curvePoint(float a, float b, float c, float d, float t) { return g.curvePoint(a, b, c, d, t); } @@ -12235,24 +12624,25 @@ public class PApplet implements PConstants { } - /** - * - * Modifies the quality of forms created with curve() and - * curveVertex(). The parameter squishy determines how the - * curve fits to the vertex points. The value 0.0 is the default value for - * squishy (this value defines the curves to be Catmull-Rom splines) - * and the value 1.0 connects all the points with straight lines. Values - * within the range -5.0 and 5.0 will deform the curves but will leave them - * recognizable and as values increase in magnitude, they will continue to deform. - * - * - * @webref shape:curves - * @webBrief Modifies the quality of forms created with curve() and - * curveVertex(). - * @param tightness amount of deformation from the original vertices - * @see PGraphics#curve(float, float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#curveVertex(float, float) - */ + /** + * + * Modifies the quality of forms created with curve() and + * curveVertex(). The parameter tightness determines how the curve + * fits to the vertex points. The value 0.0 is the default value for + * tightness (this value defines the curves to be Catmull-Rom splines) + * and the value 1.0 connects all the points with straight lines. Values within + * the range -5.0 and 5.0 will deform the curves but will leave them + * recognizable and as values increase in magnitude, they will continue to + * deform. + * + * @webref shape:curves + * @webBrief Modifies the quality of forms created with curve() and + * curveVertex(). + * @param tightness amount of deformation from the original vertices + * @see PGraphics#curve(float, float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#curveVertex(float, float) + */ public void curveTightness(float tightness) { if (recorder != null) recorder.curveTightness(tightness); g.curveTightness(tightness); @@ -12324,72 +12714,74 @@ public class PApplet implements PConstants { } - /** - * - * Modifies the location from which images draw. The default mode is - * imageMode(CORNER), which specifies the location to be the upper - * left corner and uses the fourth and fifth parameters of image() - * to set the image's width and height. The syntax - * imageMode(CORNERS) uses the second and third parameters of - * image() to set the location of one corner of the image and uses - * the fourth and fifth parameters to set the opposite corner. Use - * imageMode(CENTER) to draw images centered at the given x and y - * position.
- *
- * The parameter to imageMode() must be written in ALL CAPS because - * Processing is a case-sensitive language. - * - * - * @webref image:loading_displaying - * @webBrief Modifies the location from which images draw. - * @param mode either CORNER, CORNERS, or CENTER - * @see PApplet#loadImage(String, String) - * @see PImage - * @see PGraphics#image(PImage, float, float, float, float) - * @see PGraphics#background(float, float, float, float) - */ + /** + * + * Modifies the location from which images are drawn by changing the way in + * which parameters given to image() are intepreted.
+ *
+ * The default mode is imageMode(CORNER), which interprets the second and + * third parameters of image() as the upper-left corner of the image. If + * two additional parameters are specified, they are used to set the image's + * width and height.
+ *
+ * imageMode(CORNERS) interprets the second and third parameters of + * image() as the location of one corner, and the fourth and fifth + * parameters as the opposite corner.
+ *
+ * imageMode(CENTER) interprets the second and third parameters of + * image() as the image's center point. If two additional parameters are + * specified, they are used to set the image's width and height.
+ *
+ * The parameter must be written in ALL CAPS because Processing is a + * case-sensitive language. + * + * + * @webref image:loading_displaying + * @webBrief Modifies the location from which images draw. + * @param mode either CORNER, CORNERS, or CENTER + * @see PApplet#loadImage(String, String) + * @see PImage + * @see PGraphics#image(PImage, float, float, float, float) + * @see PGraphics#background(float, float, float, float) + */ public void imageMode(int mode) { if (recorder != null) recorder.imageMode(mode); g.imageMode(mode); } - /** - * - * Displays images to the screen. The images must be in the sketch's "data" - * directory to load correctly. Select "Add file..." from the "Sketch" menu - * to add the image. Processing currently works with GIF, JPEG, and Targa - * images. The img parameter specifies the image to display and the - * x and y parameters define the location of the image from - * its upper-left corner. The image is displayed at its original size - * unless the width and height parameters specify a different - * size.
- *
- * The imageMode() function changes the way the parameters work. For - * example, a call to imageMode(CORNERS) will change the - * width and height parameters to define the x and y values - * of the opposite corner of the image.
- *
- * The color of an image may be modified with the tint() function. - * This function will maintain transparency for GIF and PNG images. - * - * - *

Advanced

- * Starting with release 0124, when using the default (JAVA2D) renderer, - * smooth() will also improve image quality of resized images. - * - * @webref image:loading_displaying - * @webBrief Displays images to the screen. - * @param img the image to display - * @param a x-coordinate of the image by default - * @param b y-coordinate of the image by default - * @see PApplet#loadImage(String, String) - * @see PImage - * @see PGraphics#imageMode(int) - * @see PGraphics#tint(float) - * @see PGraphics#background(float, float, float, float) - * @see PGraphics#alpha(int) - */ + /** + * + * The image() function draws an image to the display window. Images must + * be in the sketch's "data" directory to load correctly. Select "Add file..." + * from the "Sketch" menu to add the image to the data directory, or just drag + * the image file onto the sketch window. Processing currently works with GIF, + * JPEG, and PNG images.
+ *
+ * The img parameter specifies the image to display and by default the + * a and b parameters define the location of its upper-left + * corner. The image is displayed at its original size unless the c and + * d parameters specify a different size. The imageMode() function + * can be used to change the way these parameters draw the image.
+ *
+ * The color of an image may be modified with the tint() function. This + * function will maintain transparency for GIF and PNG images. + * + *

Advanced

Starting with release 0124, when using the default (JAVA2D) + * renderer, smooth() will also improve image quality of resized images. + * + * @webref image:loading_displaying + * @webBrief Displays images to the screen. + * @param img the image to display + * @param a x-coordinate of the image by default + * @param b y-coordinate of the image by default + * @see PApplet#loadImage(String, String) + * @see PImage + * @see PGraphics#imageMode(int) + * @see PGraphics#tint(float) + * @see PGraphics#background(float, float, float, float) + * @see PGraphics#alpha(int) + */ public void image(PImage img, float a, float b) { if (recorder != null) recorder.image(img, a, b); g.image(img, a, b); @@ -12455,35 +12847,29 @@ public class PApplet implements PConstants { } - /** - * - * Displays shapes to the screen. The shapes must be in the sketch's "data" - * directory to load correctly. Select "Add file..." from the "Sketch" menu - * to add the shape. Processing currently works with SVG shapes only. The - * sh parameter specifies the shape to display and the x and - * y parameters define the location of the shape from its upper-left - * corner. The shape is displayed at its original size unless the - * width and height parameters specify a different size. The - * shapeMode() function changes the way the parameters work. A call - * to shapeMode(CORNERS), for example, will change the width and - * height parameters to define the x and y values of the opposite corner of - * the shape. - *

- * Note complex shapes may draw awkwardly with P3D. This renderer does not - * yet support shapes that have holes or complicated breaks. - * - * - * @webref shape:loading_displaying - * @webBrief Displays shapes to the screen. - * @param shape the shape to display - * @param x x-coordinate of the shape - * @param y y-coordinate of the shape - * @see PShape - * @see PApplet#loadShape(String) - * @see PGraphics#shapeMode(int) - * - * Convenience method to draw at a particular location. - */ + /** + * + * Draws shapes to the display window. Shapes must be in the sketch's "data" + * directory to load correctly. Select "Add file..." from the "Sketch" menu to + * add the shape. Processing currently works with SVG, OBJ, and custom-created + * shapes. The shape parameter specifies the shape to display and the + * coordinate parameters define the location of the shape from its upper-left + * corner. The shape is displayed at its original size unless the c and + * d parameters specify a different size. The shapeMode() function + * can be used to change the way these parameters are interpreted. + * + * + * @webref shape:loading_displaying + * @webBrief Displays shapes to the screen. + * @param shape the shape to display + * @param x x-coordinate of the shape + * @param y y-coordinate of the shape + * @see PShape + * @see PApplet#loadShape(String) + * @see PGraphics#shapeMode(int) + * + * Convenience method to draw at a particular location. + */ public void shape(PShape shape, float x, float y) { if (recorder != null) recorder.shape(shape, x, y); g.shape(shape, x, y); @@ -12508,114 +12894,109 @@ public class PApplet implements PConstants { } - /** - * - * Sets the current alignment for drawing text. The parameters LEFT, - * CENTER, and RIGHT set the display characteristics of the letters in - * relation to the values for the x and y parameters of the - * text() function. - *

- * In Processing 0125 and later, an optional second parameter can be used - * to vertically align the text. BASELINE is the default, and the vertical - * alignment will be reset to BASELINE if the second parameter is not used. - * The TOP and CENTER parameters are straightforward. The BOTTOM parameter - * offsets the line based on the current textDescent(). For multiple - * lines, the final line will be aligned to the bottom, with the previous - * lines appearing above it. - *

- * When using text() with width and height parameters, BASELINE is - * ignored, and treated as TOP. (Otherwise, text would by default draw - * outside the box, since BASELINE is the default setting. BASELINE is not - * a useful drawing mode for text drawn in a rectangle.) - *

- * The vertical alignment is based on the value of textAscent(), - * which many fonts do not specify correctly. It may be necessary to use a - * hack and offset by a few pixels by hand so that the offset looks - * correct. To do this as less of a hack, use some percentage of - * textAscent() or textDescent() so that the hack works even - * if you change the size of the font. - * - * - * @webref typography:attributes - * @webBrief Sets the current alignment for drawing text. - * @param alignX horizontal alignment, either LEFT, CENTER, or RIGHT - * @param alignY vertical alignment, either TOP, BOTTOM, CENTER, or BASELINE - * @see PApplet#loadFont(String) - * @see PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textSize(float) - * @see PGraphics#textAscent() - * @see PGraphics#textDescent() - */ + /** + * + * Sets the current alignment for drawing text. The parameters LEFT, CENTER, and + * RIGHT set the display characteristics of the letters in relation to the + * values for the x and y parameters of the text() + * function.
+ *
+ * An optional second parameter can be used to vertically align the text. + * BASELINE is the default, and the vertical alignment will be reset to BASELINE + * if the second parameter is not used. The TOP and CENTER parameters are + * straightforward. The BOTTOM parameter offsets the line based on the current + * textDescent(). For multiple lines, the final line will be aligned to + * the bottom, with the previous lines appearing above it.
+ *
+ * When using text() with width and height parameters, BASELINE is + * ignored, and treated as TOP. (Otherwise, text would by default draw outside + * the box, since BASELINE is the default setting. BASELINE is not a useful + * drawing mode for text drawn in a rectangle.)
+ *
+ * The vertical alignment is based on the value of textAscent(), which + * many fonts do not specify correctly. It may be necessary to use a hack and + * offset by a few pixels by hand so that the offset looks correct. To do this + * as less of a hack, use some percentage of textAscent() or + * textDescent() so that the hack works even if you change the size of + * the font. + * + * + * + * @webref typography:attributes + * @webBrief Sets the current alignment for drawing text. + * @param alignX horizontal alignment, either LEFT, CENTER, or RIGHT + * @param alignY vertical alignment, either TOP, BOTTOM, CENTER, or BASELINE + * @see PApplet#loadFont(String) + * @see PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textSize(float) + * @see PGraphics#textAscent() + * @see PGraphics#textDescent() + */ public void textAlign(int alignX, int alignY) { if (recorder != null) recorder.textAlign(alignX, alignY); g.textAlign(alignX, alignY); } - /** - * - * Returns ascent of the current font at its current size. This information - * is useful for determining the height of the font above the baseline. For - * example, adding the textAscent() and textDescent() values - * will give you the total height of the line. - * - * - * @webref typography:metrics - * @webBrief Returns ascent of the current font at its current size. - * @see PGraphics#textDescent() - */ + /** + * + * Returns ascent of the current font at its current size. This information is + * useful for determining the height of the font above the baseline. + * + * + * @webref typography:metrics + * @webBrief Returns ascent of the current font at its current size. + * @see PGraphics#textDescent() + */ public float textAscent() { return g.textAscent(); } - /** - * - * Returns descent of the current font at its current size. This - * information is useful for determining the height of the font below the - * baseline. For example, adding the textAscent() and - * textDescent() values will give you the total height of the line. - * - * - * @webref typography:metrics - * @webBrief Returns descent of the current font at its current size. - * @see PGraphics#textAscent() - */ + /** + * + * Returns descent of the current font at its current size. This information is + * useful for determining the height of the font below the baseline. + * + * @webref typography:metrics + * @webBrief Returns descent of the current font at its current size. + * @see PGraphics#textAscent() + */ public float textDescent() { return g.textDescent(); } - /** - * - * Sets the current font that will be drawn with the text() - * function. Fonts must be loaded with loadFont() before it can be - * used. This font will be used in all subsequent calls to the - * text() function. If no size parameter is input, the font - * will appear at its original size (the size it was created at with the - * "Create Font..." tool) until it is changed with textSize().

Because fonts are usually bitmaped, you should create fonts at - * the sizes that will be used most commonly. Using textFont() - * without the size parameter will result in the cleanest-looking text.

With the default (JAVA2D) and PDF renderers, it's also possible - * to enable the use of native fonts via the command - * hint(ENABLE_NATIVE_FONTS). This will produce vector text in - * JAVA2D sketches and PDF output in cases where the vector data is - * available: when the font is still installed, or the font is created via - * the createFont() function (rather than the Create Font tool). - * - * - * @webref typography:loading_displaying - * @webBrief Sets the current font that will be drawn with the text() - * function. - * @param which any variable of the type PFont - * @see PApplet#createFont(String, float, boolean) - * @see PApplet#loadFont(String) - * @see PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textSize(float) - */ + /** + * + * Sets the current font that will be drawn with the text() function. + * Fonts must be created for Processing with createFont() or loaded with + * loadFont() before they can be used. The font set through + * textFont() will be used in all subsequent calls to the text() + * function. If no size parameter is specified, the font size defaults to + * the original size (the size in which it was created with the "Create Font..." + * tool) overriding any previous calls to textFont() or + * textSize().
+ *
+ * When fonts are rendered as an image texture (as is the case with the P2D and + * P3D renderers as well as with loadFont() and vlw files), you should + * create fonts at the sizes that will be used most commonly. Using + * textFont() without the size parameter will result in the cleanest + * type.
+ *
+ * + * + * @webref typography:loading_displaying + * @webBrief Sets the current font that will be drawn with the text() + * function. + * @param which any variable of the type PFont + * @see PApplet#createFont(String, float, boolean) + * @see PApplet#loadFont(String) + * @see PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textSize(float) + */ public void textFont(PFont which) { if (recorder != null) recorder.textFont(which); g.textFont(which); @@ -12631,58 +13012,59 @@ public class PApplet implements PConstants { } - /** - * - * Sets the spacing between lines of text in units of pixels. This setting - * will be used in all subsequent calls to the text() function. - * - * - * @webref typography:attributes - * @webBrief Sets the spacing between lines of text in units of pixels. - * @param leading the size in pixels for spacing between lines - * @see PApplet#loadFont(String) - * @see PFont#PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textFont(PFont) - * @see PGraphics#textSize(float) - */ + /** + * + * Sets the spacing between lines of text in units of pixels. This setting will + * be used in all subsequent calls to the text() function. Note, however, + * that the leading is reset by textSize(). For example, if the leading + * is set to 20 with textLeading(20), then if textSize(48) is run + * at a later point, the leading will be reset to the default for the text size + * of 48. + * + * + * @webref typography:attributes + * @webBrief Sets the spacing between lines of text in units of pixels. + * @param leading the size in pixels for spacing between lines + * @see PApplet#loadFont(String) + * @see PFont#PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textFont(PFont) + * @see PGraphics#textSize(float) + */ public void textLeading(float leading) { if (recorder != null) recorder.textLeading(leading); g.textLeading(leading); } - /** - * - * Sets the way text draws to the screen. In the default configuration, the - * MODEL mode, it's possible to rotate, scale, and place letters in - * two and three dimensional space.
- *
- * The SHAPE mode draws text using the the glyph outlines of - * individual characters rather than as textures. This mode is only - * supported with the PDF and P3D renderer settings. With the - * PDF renderer, you must call textMode(SHAPE) before any - * other drawing occurs. If the outlines are not available, then - * textMode(SHAPE) will be ignored and textMode(MODEL) will - * be used instead.
- *
- * The textMode(SHAPE) option in P3D can be combined with - * beginRaw() to write vector-accurate text to 2D and 3D output - * files, for instance DXF or PDF. The SHAPE mode is - * not currently optimized for P3D, so if recording shape data, use - * textMode(MODEL) until you're ready to capture the geometry with beginRaw(). - * - * - * @webref typography:attributes - * @webBrief Sets the way text draws to the screen. - * @param mode either MODEL or SHAPE - * @see PApplet#loadFont(String) - * @see PFont#PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textFont(PFont) - * @see PGraphics#beginRaw(PGraphics) - * @see PApplet#createFont(String, float, boolean) - */ + /** + * + * Sets the way text draws to the screen, either as texture maps or as vector + * geometry. The default textMode(MODEL), uses textures to render the + * fonts. The textMode(SHAPE) mode draws text using the glyph outlines of + * individual characters rather than as textures. This mode is only supported + * with the PDF and P3D renderer settings. With the PDF + * renderer, you must call textMode(SHAPE) before any other drawing + * occurs. If the outlines are not available, then textMode(SHAPE) will + * be ignored and textMode(MODEL) will be used instead.
+ *
+ * The textMode(SHAPE) option in P3D can be combined with + * beginRaw() to write vector-accurate text to 2D and 3D output files, + * for instance DXF or PDF. The SHAPE mode is not currently + * optimized for P3D, so if recording shape data, use + * textMode(MODEL) until you're ready to capture the geometry with + * beginRaw(). + * + * @webref typography:attributes + * @webBrief Sets the way text draws to the screen. + * @param mode either MODEL or SHAPE + * @see PApplet#loadFont(String) + * @see PFont#PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textFont(PFont) + * @see PGraphics#beginRaw(PGraphics) + * @see PApplet#createFont(String, float, boolean) + */ public void textMode(int mode) { if (recorder != null) recorder.textMode(mode); g.textMode(mode); @@ -12744,40 +13126,45 @@ public class PApplet implements PConstants { } - /** - * - * Draws text to the screen. Displays the information specified in the - * data or stringdata parameters on the screen in the - * position specified by the x and y parameters and the - * optional z parameter. A default font will be used unless a font - * is set with the textFont() function. Change the color of the text - * with the fill() function. The text displays in relation to the - * textAlign() function, which gives the option to draw to the left, - * right, and center of the coordinates. - *

- * The x2 and y2 parameters define a rectangular area to - * display within and may only be used with string data. For text drawn - * inside a rectangle, the coordinates are interpreted based on the current - * rectMode() setting. - * - * - * @webref typography:loading_displaying - * @webBrief Draws text to the screen. - * @param c the alphanumeric character to be displayed - * @param x x-coordinate of text - * @param y y-coordinate of text - * @see PGraphics#textAlign(int, int) - * @see PGraphics#textFont(PFont) - * @see PGraphics#textMode(int) - * @see PGraphics#textSize(float) - * @see PGraphics#textLeading(float) - * @see PGraphics#textWidth(String) - * @see PGraphics#textAscent() - * @see PGraphics#textDescent() - * @see PGraphics#rectMode(int) - * @see PGraphics#fill(int, float) - * @see_external String - */ + /** + * + * Draws text to the screen. Displays the information specified in the first + * parameter on the screen in the position specified by the additional + * parameters. A default font will be used unless a font is set with the + * textFont() function and a default size will be used unless a font is + * set with textSize(). Change the color of the text with the + * fill() function. The text displays in relation to the + * textAlign() function, which gives the option to draw to the left, + * right, and center of the coordinates.
+ *
+ * The x2 and y2 parameters define a rectangular area to display + * within and may only be used with string data. When these parameters are + * specified, they are interpreted based on the current rectMode() + * setting. Text that does not fit completely within the rectangle specified + * will not be drawn to the screen.
+ *
+ * Note that Processing now lets you call text() without first specifying + * a PFont with textFont(). In that case, a generic sans-serif font will + * be used instead. (See the third example above.) + * + * + * @webref typography:loading_displaying + * @webBrief Draws text to the screen. + * @param c the alphanumeric character to be displayed + * @param x x-coordinate of text + * @param y y-coordinate of text + * @see PGraphics#textAlign(int, int) + * @see PGraphics#textFont(PFont) + * @see PGraphics#textMode(int) + * @see PGraphics#textSize(float) + * @see PGraphics#textLeading(float) + * @see PGraphics#textWidth(String) + * @see PGraphics#textAscent() + * @see PGraphics#textDescent() + * @see PGraphics#rectMode(int) + * @see PGraphics#fill(int, float) + * @see_external String + */ public void text(char c, float x, float y) { if (recorder != null) recorder.text(c, x, y); g.text(c, x, y); @@ -12941,7 +13328,7 @@ public class PApplet implements PConstants { * Note that these functions are always used together. They allow * you to change the style and transformation settings and later * return to what you had. When a new state is started with push(), - * it builds on the current style and transform information.
+ * it builds on the current style and transform information. *
*
* push() stores information related to the current @@ -13021,34 +13408,36 @@ public class PApplet implements PConstants { } - /** - * - * Specifies an amount to displace objects within the display window. The - * x parameter specifies left/right translation, the y - * parameter specifies up/down translation, and the z parameter - * specifies translations toward/away from the screen. Using this function - * with the z parameter requires using P3D as a parameter in - * combination with size as shown in the above example. Transformations - * apply to everything that happens after and subsequent calls to the - * function accumulates the effect. For example, calling translate(50, - * 0) and then translate(20, 0) is the same as translate(70, - * 0). If translate() is called within draw(), the - * transformation is reset when the loop begins again. This function can be - * further controlled by the pushMatrix() and popMatrix(). - * - * - * @webref transform - * @webBrief Specifies an amount to displace objects within the display window. - * @param x left/right translation - * @param y up/down translation - * @see PGraphics#popMatrix() - * @see PGraphics#pushMatrix() - * @see PGraphics#rotate(float) - * @see PGraphics#rotateX(float) - * @see PGraphics#rotateY(float) - * @see PGraphics#rotateZ(float) - * @see PGraphics#scale(float, float, float) - */ + /** + * + * Specifies an amount to displace objects within the display window. The + * x parameter specifies left/right translation, the y parameter + * specifies up/down translation, and the z parameter specifies + * translations toward/away from the screen. Using this function with the + * z parameter requires using P3D as a parameter in combination with size + * as shown in the above example.
+ *
+ * Transformations are cumulative and apply to everything that happens after and + * subsequent calls to the function accumulates the effect. For example, calling + * translate(50, 0) and then translate(20, 0) is the same as + * translate(70, 0). If translate() is called within + * draw(), the transformation is reset when the loop begins again. This + * function can be further controlled by using pushMatrix() and + * popMatrix(). + * + * + * @webref transform + * @webBrief Specifies an amount to displace objects within the display window. + * @param x left/right translation + * @param y up/down translation + * @see PGraphics#popMatrix() + * @see PGraphics#pushMatrix() + * @see PGraphics#rotate(float) + * @see PGraphics#rotateX(float) + * @see PGraphics#rotateY(float) + * @see PGraphics#rotateZ(float) + * @see PGraphics#scale(float, float, float) + */ public void translate(float x, float y) { if (recorder != null) recorder.translate(x, y); g.translate(x, y); @@ -13216,34 +13605,36 @@ public class PApplet implements PConstants { } - /** - * - * Increases or decreases the size of a shape by expanding and contracting - * vertices. Objects always scale from their relative origin to the - * coordinate system. Scale values are specified as decimal percentages. - * For example, the function call scale(2.0) increases the dimension - * of a shape by 200%. Transformations apply to everything that happens - * after and subsequent calls to the function multiply the effect. For - * example, calling scale(2.0) and then scale(1.5) is the - * same as scale(3.0). If scale() is called within - * draw(), the transformation is reset when the loop begins again. - * Using this fuction with the z parameter requires using P3D as a - * parameter for size() as shown in the example above. This function - * can be further controlled by pushMatrix() and popMatrix(). - * - * - * @webref transform - * @webBrief Increases or decreases the size of a shape by expanding and contracting - * vertices. - * @param s percentage to scale the object - * @see PGraphics#pushMatrix() - * @see PGraphics#popMatrix() - * @see PGraphics#translate(float, float, float) - * @see PGraphics#rotate(float) - * @see PGraphics#rotateX(float) - * @see PGraphics#rotateY(float) - * @see PGraphics#rotateZ(float) - */ + /** + * + * Increases or decreases the size of a shape by expanding and contracting + * vertices. Objects always scale from their relative origin to the coordinate + * system. Scale values are specified as decimal percentages. For example, the + * function call scale(2.0) increases the dimension of a shape by + * 200%.
+ *
+ * Transformations apply to everything that happens after and subsequent calls + * to the function multiply the effect. For example, calling scale(2.0) + * and then scale(1.5) is the same as scale(3.0). If + * scale() is called within draw(), the transformation is reset + * when the loop begins again. Using this function with the z parameter + * requires using P3D as a parameter for size(), as shown in the third + * example above. This function can be further controlled with + * pushMatrix() and popMatrix(). + * + * + * @webref transform + * @webBrief Increases or decreases the size of a shape by expanding and + * contracting vertices. + * @param s percentage to scale the object + * @see PGraphics#pushMatrix() + * @see PGraphics#popMatrix() + * @see PGraphics#translate(float, float, float) + * @see PGraphics#rotate(float) + * @see PGraphics#rotateX(float) + * @see PGraphics#rotateY(float) + * @see PGraphics#rotateZ(float) + */ public void scale(float s) { if (recorder != null) recorder.scale(s); g.scale(s); @@ -13345,19 +13736,19 @@ public class PApplet implements PConstants { } - /** - * - * Replaces the current matrix with the identity matrix. The equivalent - * function in OpenGL is glLoadIdentity(). - * - * - * @webref transform - * @webBrief Replaces the current matrix with the identity matrix. - * @see PGraphics#pushMatrix() - * @see PGraphics#popMatrix() - * @see PGraphics#applyMatrix(PMatrix) - * @see PGraphics#printMatrix() - */ + /** + * + * Replaces the current matrix with the identity matrix. The equivalent function + * in OpenGL is glLoadIdentity(). + * + * + * @webref transform + * @webBrief Replaces the current matrix with the identity matrix. + * @see PGraphics#pushMatrix() + * @see PGraphics#popMatrix() + * @see PGraphics#applyMatrix(PMatrix) + * @see PGraphics#printMatrix() + */ public void resetMatrix() { if (recorder != null) recorder.resetMatrix(); g.resetMatrix(); @@ -13620,21 +14011,21 @@ public class PApplet implements PConstants { } - /** - * - * Sets an orthographic projection and defines a parallel clipping volume. - * All objects with the same dimension appear the same size, regardless of - * whether they are near or far from the camera. The parameters to this - * function specify the clipping volume where left and right are the - * minimum and maximum x values, top and bottom are the minimum and maximum - * y values, and near and far are the minimum and maximum z values. If no - * parameters are given, the default is used: ortho(0, width, 0, height, - * -10, 10). - * - * - * @webref lights_camera:camera - * @webBrief Sets an orthographic projection and defines a parallel clipping volume. - */ + /** + * + * Sets an orthographic projection and defines a parallel clipping volume. All + * objects with the same dimension appear the same size, regardless of whether + * they are near or far from the camera. The parameters to this function specify + * the clipping volume where left and right are the minimum and maximum x + * values, top and bottom are the minimum and maximum y values, and near and far + * are the minimum and maximum z values. If no parameters are given, the default + * is used: ortho(-width/2, width/2, -height/2, height/2). + * + * + * @webref lights_camera:camera + * @webBrief Sets an orthographic projection and defines a parallel clipping + * volume. + */ public void ortho() { if (recorder != null) recorder.ortho(); g.ortho(); @@ -13702,26 +14093,44 @@ public class PApplet implements PConstants { } - /** - * - * Sets a perspective matrix defined through the parameters. Works like - * glFrustum, except it wipes out the current perspective matrix rather - * than muliplying itself with it. - * - * - * @webref lights_camera:camera - * @webBrief Sets a perspective matrix defined through the parameters. - * @param left left coordinate of the clipping plane - * @param right right coordinate of the clipping plane - * @param bottom bottom coordinate of the clipping plane - * @param top top coordinate of the clipping plane - * @param near near component of the clipping plane; must be greater than zero - * @param far far component of the clipping plane; must be greater than the near value - * @see PGraphics#camera(float, float, float, float, float, float, float, float, float) - * @see PGraphics#beginCamera() - * @see PGraphics#endCamera() - * @see PGraphics#perspective(float, float, float, float) - */ + /** + * + * Sets a perspective matrix as defined by the parameters.
+ *
+ * A frustum is a geometric form: a pyramid with its top cut off. With the + * viewer's eye at the imaginary top of the pyramid, the six planes of the + * frustum act as clipping planes when rendering a 3D view. Thus, any form + * inside the clipping planes is rendered and visible; anything outside those + * planes is not visible.
+ *
+ * Setting the frustum has the effect of changing the perspective with + * which the scene is rendered. This can be achieved more simply in many cases + * by using perspective().
+ *
+ * Note that the near value must be greater than zero (as the point of the + * frustum "pyramid" cannot converge "behind" the viewer). Similarly, the far + * value must be greater than the near value (as the "far" plane of the frustum + * must be "farther away" from the viewer than the near plane).
+ *
+ * Works like glFrustum, except it wipes out the current perspective matrix + * rather than multiplying itself with it. + * + * + * @webref lights_camera:camera + * @webBrief Sets a perspective matrix defined through the parameters. + * @param left left coordinate of the clipping plane + * @param right right coordinate of the clipping plane + * @param bottom bottom coordinate of the clipping plane + * @param top top coordinate of the clipping plane + * @param near near component of the clipping plane; must be greater than zero + * @param far far component of the clipping plane; must be greater than the + * near value + * @see PGraphics#camera(float, float, float, float, float, float, float, float, + * float) + * @see PGraphics#beginCamera() + * @see PGraphics#endCamera() + * @see PGraphics#perspective(float, float, float, float) + */ public void frustum(float left, float right, float bottom, float top, float near, float far) { @@ -13962,80 +14371,68 @@ public class PApplet implements PConstants { } - /** - * - * Sets the width of the stroke used for lines, points, and the border - * around shapes. All widths are set in units of pixels. - *

- * When drawing with P3D, series of connected lines (such as the stroke - * around a polygon, triangle, or ellipse) produce unattractive results - * when a thick stroke weight is set (see - * Issue 123). With P3D, the minimum and maximum values for - * strokeWeight() are controlled by the graphics card and the - * operating system's OpenGL implementation. For instance, the thickness - * may not go higher than 10 pixels. - * - * - * @webref shape:attributes - * @webBrief Sets the width of the stroke used for lines, points, and the border - * around shapes. - * @param weight the weight (in pixels) of the stroke - * @see PGraphics#stroke(int, float) - * @see PGraphics#strokeJoin(int) - * @see PGraphics#strokeCap(int) - */ + /** + * + * Sets the width of the stroke used for lines, points, and the border around + * shapes. All widths are set in units of pixels.
+ *
+ * Using point() with strokeWeight(1) or smaller may draw nothing to the screen, + * depending on the graphics settings of the computer. Workarounds include + * setting the pixel using set() or drawing the point using either + * circle() or square(). + * + * + * @webref shape:attributes + * @webBrief Sets the width of the stroke used for lines, points, and the border + * around shapes. + * @param weight the weight (in pixels) of the stroke + * @see PGraphics#stroke(int, float) + * @see PGraphics#strokeJoin(int) + * @see PGraphics#strokeCap(int) + */ public void strokeWeight(float weight) { if (recorder != null) recorder.strokeWeight(weight); g.strokeWeight(weight); } - /** - * - * Sets the style of the joints which connect line segments. These joints - * are either mitered, beveled, or rounded and specified with the - * corresponding parameters MITER, BEVEL, and ROUND. The default joint is - * MITER. - *

- * This function is not available with the P3D renderer, (see - * Issue 123). More information about the renderers can be found in the - * size() reference. - * - * - * @webref shape:attributes - * @webBrief Sets the style of the joints which connect line segments. - * @param join either MITER, BEVEL, ROUND - * @see PGraphics#stroke(int, float) - * @see PGraphics#strokeWeight(float) - * @see PGraphics#strokeCap(int) - */ + /** + * + * Sets the style of the joints which connect line segments. These joints are + * either mitered, beveled, or rounded and specified with the corresponding + * parameters MITER, BEVEL, and ROUND. The default joint is MITER. + * + * + * @webref shape:attributes + * @webBrief Sets the style of the joints which connect line segments. + * @param join either MITER, BEVEL, ROUND + * @see PGraphics#stroke(int, float) + * @see PGraphics#strokeWeight(float) + * @see PGraphics#strokeCap(int) + */ public void strokeJoin(int join) { if (recorder != null) recorder.strokeJoin(join); g.strokeJoin(join); } - /** - * - * Sets the style for rendering line endings. These ends are either - * squared, extended, or rounded and specified with the corresponding - * parameters SQUARE, PROJECT, and ROUND. The default cap is ROUND. - *

- * This function is not available with the P3D renderer (see - * Issue 123). More information about the renderers can be found in the - * size() reference. - * - * @webref shape:attributes - * @webBrief Sets the style for rendering line endings. - * @param cap either SQUARE, PROJECT, or ROUND - * @see PGraphics#stroke(int, float) - * @see PGraphics#strokeWeight(float) - * @see PGraphics#strokeJoin(int) - * @see PApplet#size(int, int, String, String) - */ + /** + * + * Sets the style for rendering line endings. These ends are either squared, + * extended, or rounded, each of which specified with the corresponding + * parameters: SQUARE, PROJECT, and ROUND. The default cap is ROUND.
+ *
+ * To make point() appear square, use strokeCap(PROJECT). Using + * strokeCap(SQUARE) (no cap) causes points to become invisible. + * + * @webref shape:attributes + * @webBrief Sets the style for rendering line endings. + * @param cap either SQUARE, PROJECT, or ROUND + * @see PGraphics#stroke(int, float) + * @see PGraphics#strokeWeight(float) + * @see PGraphics#strokeJoin(int) + * @see PApplet#size(int, int, String, String) + */ public void strokeCap(int cap) { if (recorder != null) recorder.strokeCap(cap); g.strokeCap(cap); @@ -14060,38 +14457,42 @@ public class PApplet implements PConstants { } - /** - * - * Sets the color used to draw lines and borders around shapes. This color - * is either specified in terms of the RGB or HSB color depending on the - * current colorMode() (the default color space is RGB, with each - * value in the range from 0 to 255). - *

- * When using hexadecimal notation to specify a color, use "#" or "0x" - * before the values (e.g. #CCFFAA, 0xFFCCFFAA). The # syntax uses six - * digits to specify a color (the way colors are specified in HTML and - * CSS). When using the hexadecimal notation starting with "0x", the - * hexadecimal value must be specified with eight characters; the first two - * characters define the alpha component and the remainder the red, green, - * and blue components. - *

- * The value for the parameter "gray" must be less than or equal to the - * current maximum value as specified by colorMode(). The default - * maximum value is 255. - * - * @webref color:setting - * @webBrief Sets the color used to draw lines and borders around shapes. - * @param rgb color value in hexadecimal notation - * @see PGraphics#noStroke() - * @see PGraphics#strokeWeight(float) - * @see PGraphics#strokeJoin(int) - * @see PGraphics#strokeCap(int) - * @see PGraphics#fill(int, float) - * @see PGraphics#noFill() - * @see PGraphics#tint(int, float) - * @see PGraphics#background(float, float, float, float) - * @see PGraphics#colorMode(int, float, float, float, float) - */ + /** + * + * Sets the color used to draw lines and borders around shapes. This color is + * either specified in terms of the RGB or HSB color depending on the current + * colorMode(). The default color space is RGB, with each value in the + * range from 0 to 255.
+ *
+ * When using hexadecimal notation to specify a color, use "#" or + * "0x" before the values (e.g., #CCFFAA or 0xFFCCFFAA). + * The # syntax uses six digits to specify a color (just as colors are + * typically specified in HTML and CSS). When using the hexadecimal notation + * starting with "0x", the hexadecimal value must be specified with eight + * characters; the first two characters define the alpha component, and the + * remainder define the red, green, and blue components.
+ *
+ * The value for the gray parameter must be less than or equal to the current + * maximum value as specified by colorMode(). The default maximum value + * is 255.
+ *
+ * When drawing in 2D with the default renderer, you may need + * hint(ENABLE_STROKE_PURE) to improve drawing quality (at the expense of + * performance). See the hint() documentation for more details. + * + * @webref color:setting + * @webBrief Sets the color used to draw lines and borders around shapes. + * @param rgb color value in hexadecimal notation + * @see PGraphics#noStroke() + * @see PGraphics#strokeWeight(float) + * @see PGraphics#strokeJoin(int) + * @see PGraphics#strokeCap(int) + * @see PGraphics#fill(int, float) + * @see PGraphics#noFill() + * @see PGraphics#tint(int, float) + * @see PGraphics#background(float, float, float, float) + * @see PGraphics#colorMode(int, float, float, float, float) + */ public void stroke(int rgb) { if (recorder != null) recorder.stroke(rgb); g.stroke(rgb); @@ -14158,39 +14559,39 @@ public class PApplet implements PConstants { } - /** - * - * Sets the fill value for displaying images. Images can be tinted to - * specified colors or made transparent by setting the alpha.
- *
- * To make an image transparent, but not change it's color, use white as - * the tint color and specify an alpha value. For instance, tint(255, 128) - * will make an image 50% transparent (unless colorMode() has been - * used).
- *
- * When using hexadecimal notation to specify a color, use "#" or "0x" - * before the values (e.g. #CCFFAA, 0xFFCCFFAA). The # syntax uses six - * digits to specify a color (the way colors are specified in HTML and - * CSS). When using the hexadecimal notation starting with "0x", the - * hexadecimal value must be specified with eight characters; the first two - * characters define the alpha component and the remainder the red, green, - * and blue components.
- *
- * The value for the parameter "gray" must be less than or equal to the - * current maximum value as specified by colorMode(). The default - * maximum value is 255.
- *
- * The tint() function is also used to control the coloring of - * textures in 3D. - * - * - * @webref image:loading_displaying - * @webBrief Sets the fill value for displaying images. - * @usage web_application - * @param rgb color value in hexadecimal notation - * @see PGraphics#noTint() - * @see PGraphics#image(PImage, float, float, float, float) - */ + /** + * + * Sets the fill value for displaying images. Images can be tinted to specified + * colors or made transparent by including an alpha value.
+ *
+ * To apply transparency to an image without affecting its color, use white as + * the tint color and specify an alpha value. For instance, tint(255, + * 128) will make an image 50% transparent (assuming the default alpha range + * of 0-255, which can be changed with colorMode()).
+ *
+ * When using hexadecimal notation to specify a color, use "#" or + * "0x" before the values (e.g., #CCFFAA or 0xFFCCFFAA). + * The # syntax uses six digits to specify a color (just as colors are + * typically specified in HTML and CSS). When using the hexadecimal notation + * starting with "0x", the hexadecimal value must be specified with eight + * characters; the first two characters define the alpha component, and the + * remainder define the red, green, and blue components.
+ *
+ * The value for the gray parameter must be less than or equal to the current + * maximum value as specified by colorMode(). The default maximum value + * is 255.
+ *
+ * The tint() function is also used to control the coloring of textures + * in 3D. + * + * + * @webref image:loading_displaying + * @webBrief Sets the fill value for displaying images. + * @usage web_application + * @param rgb color value in hexadecimal notation + * @see PGraphics#noTint() + * @see PGraphics#image(PImage, float, float, float, float) + */ public void tint(int rgb) { if (recorder != null) recorder.tint(rgb); g.tint(rgb); @@ -14543,29 +14944,30 @@ public class PApplet implements PConstants { } - /** - * - * Adds an ambient light. Ambient light doesn't come from a specific - * direction, the rays have light have bounced around so much that objects - * are evenly lit from all sides. Ambient lights are almost always used in - * combination with other types of lights. Lights need to be included in - * the draw() to remain persistent in a looping program. Placing - * them in the setup() of a looping program will cause them to only - * have an effect the first time through the loop. The effect of the - * parameters is determined by the current color mode. - * - * - * @webref lights_camera:lights - * @webBrief Adds an ambient light. - * @usage web_application - * @param v1 red or hue value (depending on current color mode) - * @param v2 green or saturation value (depending on current color mode) - * @param v3 blue or brightness value (depending on current color mode) - * @see PGraphics#lights() - * @see PGraphics#directionalLight(float, float, float, float, float, float) - * @see PGraphics#pointLight(float, float, float, float, float, float) - * @see PGraphics#spotLight(float, float, float, float, float, float, float, float, float, float, float) - */ + /** + * + * Adds an ambient light. Ambient light doesn't come from a specific direction, + * the rays of light have bounced around so much that objects are evenly lit + * from all sides. Ambient lights are almost always used in combination with + * other types of lights. Lights need to be included in the draw() to + * remain persistent in a looping program. Placing them in the setup() of + * a looping program will cause them to only have an effect the first time + * through the loop. The v1, v2, and v3 parameters are + * interpreted as either RGB or HSB values, depending on the current color mode. + * + * + * @webref lights_camera:lights + * @webBrief Adds an ambient light. + * @usage web_application + * @param v1 red or hue value (depending on current color mode) + * @param v2 green or saturation value (depending on current color mode) + * @param v3 blue or brightness value (depending on current color mode) + * @see PGraphics#lights() + * @see PGraphics#directionalLight(float, float, float, float, float, float) + * @see PGraphics#pointLight(float, float, float, float, float, float) + * @see PGraphics#spotLight(float, float, float, float, float, float, float, + * float, float, float, float) + */ public void ambientLight(float v1, float v2, float v3) { if (recorder != null) recorder.ambientLight(v1, v2, v3); g.ambientLight(v1, v2, v3); @@ -14620,31 +15022,31 @@ public class PApplet implements PConstants { } - /** - * - * Adds a point light. Lights need to be included in the draw() to - * remain persistent in a looping program. Placing them in the - * setup() of a looping program will cause them to only have an - * effect the first time through the loop. The affect of the v1, - * v2, and v3 parameters is determined by the current color - * mode. The x, y, and z parameters set the position - * of the light. - * - * - * @webref lights_camera:lights - * @webBrief Adds a point light. - * @usage web_application - * @param v1 red or hue value (depending on current color mode) - * @param v2 green or saturation value (depending on current color mode) - * @param v3 blue or brightness value (depending on current color mode) - * @param x x-coordinate of the light - * @param y y-coordinate of the light - * @param z z-coordinate of the light - * @see PGraphics#lights() - * @see PGraphics#directionalLight(float, float, float, float, float, float) - * @see PGraphics#ambientLight(float, float, float, float, float, float) - * @see PGraphics#spotLight(float, float, float, float, float, float, float, float, float, float, float) - */ + /** + * + * Adds a point light. Lights need to be included in the draw() to remain + * persistent in a looping program. Placing them in the setup() of a + * looping program will cause them to only have an effect the first time through + * the loop. The v1, v2, and v3 parameters are interpreted + * as either RGB or HSB values, depending on the current color mode. The + * x, y, and z parameters set the position of the light. + * + * + * @webref lights_camera:lights + * @webBrief Adds a point light. + * @usage web_application + * @param v1 red or hue value (depending on current color mode) + * @param v2 green or saturation value (depending on current color mode) + * @param v3 blue or brightness value (depending on current color mode) + * @param x x-coordinate of the light + * @param y y-coordinate of the light + * @param z z-coordinate of the light + * @see PGraphics#lights() + * @see PGraphics#directionalLight(float, float, float, float, float, float) + * @see PGraphics#ambientLight(float, float, float, float, float, float) + * @see PGraphics#spotLight(float, float, float, float, float, float, float, + * float, float, float, float) + */ public void pointLight(float v1, float v2, float v3, float x, float y, float z) { if (recorder != null) recorder.pointLight(v1, v2, v3, x, y, z); @@ -14652,38 +15054,40 @@ public class PApplet implements PConstants { } - /** - * - * Adds a spot light. Lights need to be included in the draw() to - * remain persistent in a looping program. Placing them in the - * setup() of a looping program will cause them to only have an - * effect the first time through the loop. The affect of the v1, - * v2, and v3 parameters is determined by the current color - * mode. The x, y, and z parameters specify the - * position of the light and nx, ny, nz specify the - * direction or light. The angle parameter affects angle of the - * spotlight cone. - * - * - * @webref lights_camera:lights - * @webBrief Adds a spot light. - * @usage web_application - * @param v1 red or hue value (depending on current color mode) - * @param v2 green or saturation value (depending on current color mode) - * @param v3 blue or brightness value (depending on current color mode) - * @param x x-coordinate of the light - * @param y y-coordinate of the light - * @param z z-coordinate of the light - * @param nx direction along the x axis - * @param ny direction along the y axis - * @param nz direction along the z axis - * @param angle angle of the spotlight cone - * @param concentration exponent determining the center bias of the cone - * @see PGraphics#lights() - * @see PGraphics#directionalLight(float, float, float, float, float, float) - * @see PGraphics#pointLight(float, float, float, float, float, float) - * @see PGraphics#ambientLight(float, float, float, float, float, float) - */ + /** + * + * Adds a spot light. Lights need to be included in the draw() to remain + * persistent in a looping program. Placing them in the setup() of a + * looping program will cause them to only have an effect the first time through + * the loop. The v1, v2, and v3 parameters are interpreted + * as either RGB or HSB values, depending on the current color mode. The + * x, y, and z parameters specify the position of the light + * and nx, ny, nz specify the direction of light. The + * angle parameter affects angle of the spotlight cone, while + * concentration sets the bias of light focusing toward the center of + * that cone. + * + * @webref lights_camera:lights + * @webBrief Adds a spot light. + * @usage web_application + * @param v1 red or hue value (depending on current color mode) + * @param v2 green or saturation value (depending on current color + * mode) + * @param v3 blue or brightness value (depending on current color + * mode) + * @param x x-coordinate of the light + * @param y y-coordinate of the light + * @param z z-coordinate of the light + * @param nx direction along the x axis + * @param ny direction along the y axis + * @param nz direction along the z axis + * @param angle angle of the spotlight cone + * @param concentration exponent determining the center bias of the cone + * @see PGraphics#lights() + * @see PGraphics#directionalLight(float, float, float, float, float, float) + * @see PGraphics#pointLight(float, float, float, float, float, float) + * @see PGraphics#ambientLight(float, float, float, float, float, float) + */ public void spotLight(float v1, float v2, float v3, float x, float y, float z, float nx, float ny, float nz, @@ -14693,35 +15097,38 @@ public class PApplet implements PConstants { } - /** - * - * Sets the falloff rates for point lights, spot lights, and ambient - * lights. The parameters are used to determine the falloff with the - * following equation:

d = distance from light position to - * vertex position
falloff = 1 / (CONSTANT + d * LINEAR + (d*d) * - * QUADRATIC)

Like fill(), it affects only the elements - * which are created after it in the code. The default value if - * LightFalloff(1.0, 0.0, 0.0). Thinking about an ambient light with - * a falloff can be tricky. It is used, for example, if you wanted a region - * of your scene to be lit ambiently one color and another region to be lit - * ambiently by another color, you would use an ambient light with location - * and falloff. You can think of it as a point light that doesn't care - * which direction a surface is facing. - * - * - * @webref lights_camera:lights - * @webBrief Sets the falloff rates for point lights, spot lights, and ambient - * lights. - * @usage web_application - * @param constant constant value or determining falloff - * @param linear linear value for determining falloff - * @param quadratic quadratic value for determining falloff - * @see PGraphics#lights() - * @see PGraphics#ambientLight(float, float, float, float, float, float) - * @see PGraphics#pointLight(float, float, float, float, float, float) - * @see PGraphics#spotLight(float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#lightSpecular(float, float, float) - */ + /** + * + * Sets the falloff rates for point lights, spot lights, and ambient lights. + * Like fill(), it affects only the elements which are created after it + * in the code. The default value is lightFalloff(1.0, 0.0, 0.0), and the + * parameters are used to calculate the falloff with the following + * equation:
+ *
+ * d = distance from light position to vertex position
+ * falloff = 1 / (CONSTANT + d * LINEAR + (d*d) * QUADRATIC)
+ *
+ * Thinking about an ambient light with a falloff can be tricky. If you want a + * region of your scene to be lit ambiently with one color and another region to + * be lit ambiently with another color, you could use an ambient light with + * location and falloff. You can think of it as a point light that doesn't care + * which direction a surface is facing. + * + * + * @webref lights_camera:lights + * @webBrief Sets the falloff rates for point lights, spot lights, and ambient + * lights. + * @usage web_application + * @param constant constant value or determining falloff + * @param linear linear value for determining falloff + * @param quadratic quadratic value for determining falloff + * @see PGraphics#lights() + * @see PGraphics#ambientLight(float, float, float, float, float, float) + * @see PGraphics#pointLight(float, float, float, float, float, float) + * @see PGraphics#spotLight(float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#lightSpecular(float, float, float) + */ public void lightFalloff(float constant, float linear, float quadratic) { if (recorder != null) recorder.lightFalloff(constant, linear, quadratic); g.lightFalloff(constant, linear, quadratic); @@ -14757,42 +15164,49 @@ public class PApplet implements PConstants { } - /** - * - * The background() function sets the color used for the background - * of the Processing window. The default background is light gray. In the - * draw() function, the background color is used to clear the - * display window at the beginning of each frame. - *

- * An image can also be used as the background for a sketch, however its - * width and height must be the same size as the sketch window. To resize - * an image 'b' to the size of the sketch window, use b.resize(width, height). - *

- * Images used as background will ignore the current tint() setting. - *

- * It is not possible to use transparency (alpha) in background colors with - * the main drawing surface, however they will work properly with createGraphics(). - * - * - *

Advanced

- *

Clear the background with a color that includes an alpha value. This can - * only be used with objects created by createGraphics(), because the main - * drawing surface cannot be set transparent.

- *

It might be tempting to use this function to partially clear the screen - * on each frame, however that's not how this function works. When calling - * background(), the pixels will be replaced with pixels that have that level - * of transparency. To do a semi-transparent overlay, use fill() with alpha - * and draw a rectangle.

- * - * @webref color:setting - * @webBrief Sets the color used for the background of the Processing window. - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#stroke(float) - * @see PGraphics#fill(float) - * @see PGraphics#tint(float) - * @see PGraphics#colorMode(int) - */ + /** + * + * The background() function sets the color used for the background of + * the Processing window. The default background is light gray. This function is + * typically used within draw() to clear the display window at the + * beginning of each frame, but it can be used inside setup() to set the + * background on the first frame of animation or if the backgound need only be + * set once.
+ *
+ * An image can also be used as the background for a sketch, although the + * image's width and height must match that of the sketch window. Images used + * with background() will ignore the current tint() setting. To + * resize an image to the size of the sketch window, use image.resize(width, + * height).
+ *
+ * It is not possible to use the transparency alpha parameter with + * background colors on the main drawing surface. It can only be used along with + * a PGraphics object and createGraphics(). + * + * + *

Advanced

+ *

+ * Clear the background with a color that includes an alpha value. This can only + * be used with objects created by createGraphics(), because the main drawing + * surface cannot be set transparent. + *

+ *

+ * It might be tempting to use this function to partially clear the screen on + * each frame, however that's not how this function works. When calling + * background(), the pixels will be replaced with pixels that have that level of + * transparency. To do a semi-transparent overlay, use fill() with alpha and + * draw a rectangle. + *

+ * + * @webref color:setting + * @webBrief Sets the color used for the background of the Processing window. + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#stroke(float) + * @see PGraphics#fill(float) + * @see PGraphics#tint(float) + * @see PGraphics#colorMode(int) + */ public void background(int rgb) { if (recorder != null) recorder.background(rgb); g.background(rgb); @@ -14848,6 +15262,7 @@ public class PApplet implements PConstants { * can be entirely or partially transparent. This function clears * everything in a PGraphics object to make all of the pixels * 100% transparent. + * * @webref color:setting * @webBrief Clears the pixels within a buffer. */ @@ -14877,26 +15292,36 @@ public class PApplet implements PConstants { } - /** - * - * Changes the way Processing interprets color data. By default, the - * parameters for fill(), stroke(), background(), and - * color() are defined by values between 0 and 255 using the RGB - * color model. The colorMode() function is used to change the - * numerical range used for specifying colors and to switch color systems. - * For example, calling colorMode(RGB, 1.0) will specify that values - * are specified between 0 and 1. The limits for defining colors are - * altered by setting the parameters range1, range2, range3, and range 4. - * - * - * @webref color:setting - * @webBrief Changes the way Processing interprets color data. - * @usage web_application - * @param mode Either RGB or HSB, corresponding to Red/Green/Blue and Hue/Saturation/Brightness - * @see PGraphics#background(float) - * @see PGraphics#fill(float) - * @see PGraphics#stroke(float) - */ + /** + * + * Changes the way Processing interprets color data. By default, the parameters + * for fill(), stroke(), background(), and color() + * are defined by values between 0 and 255 using the RGB color model. The + * colorMode() function is used to change the numerical range used for + * specifying colors and to switch color systems. For example, calling + * colorMode(RGB, 1.0) will specify that values are specified between 0 + * and 1. The limits for defining colors are altered by setting the parameters + * max, max1, max2, max3, and maxA.
+ *
+ * After changing the range of values for colors with code like + * colorMode(HSB, 360, 100, 100), those ranges remain in use until they + * are explicitly changed again. For example, after running colorMode(HSB, + * 360, 100, 100) and then changing back to colorMode(RGB), the range + * for R will be 0 to 360 and the range for G and B will be 0 to 100. To avoid + * this, be explicit about the ranges when changing the color mode. For + * instance, instead of colorMode(RGB), write colorMode(RGB, 255, 255, + * 255). + * + * + * @webref color:setting + * @webBrief Changes the way Processing interprets color data. + * @usage web_application + * @param mode Either RGB or HSB, corresponding to Red/Green/Blue and + * Hue/Saturation/Brightness + * @see PGraphics#background(float) + * @see PGraphics#fill(float) + * @see PGraphics#stroke(float) + */ public void colorMode(int mode) { if (recorder != null) recorder.colorMode(mode); g.colorMode(mode); @@ -14953,91 +15378,115 @@ public class PApplet implements PConstants { } - /** - * - * Extracts the red value from a color, scaled to match current - * colorMode(). This value is always returned as a float so be - * careful not to assign it to an int value.

The red() function - * is easy to use and undestand, but is slower than another technique. To - * achieve the same results when working in colorMode(RGB, 255), but - * with greater speed, use the >> (right shift) operator with a bit - * mask. For example, the following two lines of code are equivalent:
float r1 = red(myColor);
float r2 = myColor >> 16
-   * & 0xFF;
- * - * - * @webref color:creating_reading - * @webBrief Extracts the red value from a color, scaled to match current colorMode(). - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#green(int) - * @see PGraphics#blue(int) - * @see PGraphics#alpha(int) - * @see PGraphics#hue(int) - * @see PGraphics#saturation(int) - * @see PGraphics#brightness(int) - * @see_external rightshift - */ + /** + * + * Extracts the red value from a color, scaled to match current + * colorMode(). The value is always returned as a float, so be careful + * not to assign it to an int value.
+ *
+ * The red() function is easy to use and understand, but it is slower + * than a technique called bit shifting. When working in colorMode(RGB, + * 255), you can acheive the same results as red() but with greater + * speed by using the right shift operator (>>) with a bit mask. For + * example, the following two lines of code are equivalent means of getting the + * red value of the color value c:
+ *
+ * + * 
+	 * float r1 = red(c); // Simpler, but slower to calculate
+	 * float r2 = c >> 16 & 0xFF; // Very fast to calculate
+	 *
+ * + * + * @webref color:creating_reading + * @webBrief Extracts the red value from a color, scaled to match current + * colorMode(). + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#green(int) + * @see PGraphics#blue(int) + * @see PGraphics#alpha(int) + * @see PGraphics#hue(int) + * @see PGraphics#saturation(int) + * @see PGraphics#brightness(int) + * @see_external rightshift + */ public final float red(int rgb) { return g.red(rgb); } - /** - * - * Extracts the green value from a color, scaled to match current - * colorMode(). This value is always returned as a float so be - * careful not to assign it to an int value.

The green() - * function is easy to use and undestand, but is slower than another - * technique. To achieve the same results when working in colorMode(RGB, - * 255), but with greater speed, use the >> (right shift) - * operator with a bit mask. For example, the following two lines of code - * are equivalent:
float r1 = green(myColor);
float r2 =
-   * myColor >> 8 & 0xFF;
- * - * - * @webref color:creating_reading - * @webBrief Extracts the green value from a color, scaled to match current colorMode(). - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#red(int) - * @see PGraphics#blue(int) - * @see PGraphics#alpha(int) - * @see PGraphics#hue(int) - * @see PGraphics#saturation(int) - * @see PGraphics#brightness(int) - * @see_external rightshift - */ + /** + * + * Extracts the green value from a color, scaled to match current + * colorMode(). The value is always returned as a float, so be careful + * not to assign it to an int value.
+ *
+ * The green() function is easy to use and understand, but it is slower + * than a technique called bit shifting. When working in colorMode(RGB, + * 255), you can acheive the same results as green() but with greater + * speed by using the right shift operator (>>) with a bit mask. For + * example, the following two lines of code are equivalent means of getting the + * green value of the color value c:
+ *
+ * + * 
+	 * float g1 = green(c); // Simpler, but slower to calculate
+	 * float g2 = c >> 8 & 0xFF; // Very fast to calculate
+	 *
+ * + * + * @webref color:creating_reading + * @webBrief Extracts the green value from a color, scaled to match current + * colorMode(). + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#red(int) + * @see PGraphics#blue(int) + * @see PGraphics#alpha(int) + * @see PGraphics#hue(int) + * @see PGraphics#saturation(int) + * @see PGraphics#brightness(int) + * @see_external rightshift + */ public final float green(int rgb) { return g.green(rgb); } - /** - * - * Extracts the blue value from a color, scaled to match current - * colorMode(). This value is always returned as a float so be - * careful not to assign it to an int value.

The blue() - * function is easy to use and undestand, but is slower than another - * technique. To achieve the same results when working in colorMode(RGB, - * 255), but with greater speed, use a bit mask to remove the other - * color components. For example, the following two lines of code are - * equivalent:
float r1 = blue(myColor);
float r2 = myColor
-   * & 0xFF;
- * - * - * @webref color:creating_reading - * @webBrief Extracts the blue value from a color, scaled to match current colorMode(). - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#red(int) - * @see PGraphics#green(int) - * @see PGraphics#alpha(int) - * @see PGraphics#hue(int) - * @see PGraphics#saturation(int) - * @see PGraphics#brightness(int) - * @see_external rightshift - */ + /** + * + * Extracts the blue value from a color, scaled to match current + * colorMode(). The value is always returned as a float, so be careful + * not to assign it to an int value.
+ *
+ * The blue() function is easy to use and understand, but it is slower + * than a technique called bit masking. When working in colorMode(RGB, + * 255), you can acheive the same results as blue() but with greater + * speed by using a bit mask to remove the other color components. For example, + * the following two lines of code are equivalent means of getting the blue + * value of the color value c:
+ *
+ * + * 
+	 * float b1 = blue(c); // Simpler, but slower to calculate
+	 * float b2 = c & 0xFF; // Very fast to calculate
+	 *
+ * + * + * @webref color:creating_reading + * @webBrief Extracts the blue value from a color, scaled to match current + * colorMode(). + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#red(int) + * @see PGraphics#green(int) + * @see PGraphics#alpha(int) + * @see PGraphics#hue(int) + * @see PGraphics#saturation(int) + * @see PGraphics#brightness(int) + * @see_external rightshift + */ public final float blue(int rgb) { return g.blue(rgb); } @@ -15341,57 +15790,67 @@ public class PApplet implements PConstants { } - /** - * - * Filters an image as defined by one of the following modes:

THRESHOLD - converts the image to black and white pixels depending if - * they are above or below the threshold defined by the level parameter. - * The level must be between 0.0 (black) and 1.0(white). If no level is - * specified, 0.5 is used.
- *
- * GRAY - converts any colors in the image to grayscale equivalents
- *
- * INVERT - sets each pixel to its inverse value
- *
- * POSTERIZE - limits each channel of the image to the number of colors - * specified as the level parameter
- *
- * BLUR - executes a Guassian blur with the level parameter specifying the - * extent of the blurring. If no level parameter is used, the blur is - * equivalent to Guassian blur of radius 1
- *
- * OPAQUE - sets the alpha channel to entirely opaque
- *
- * ERODE - reduces the light areas with the amount defined by the level - * parameter
- *
- * DILATE - increases the light areas with the amount defined by the level parameter - * - * - *

Advanced

- * Method to apply a variety of basic filters to this image. - *

- *

    - *
  • filter(BLUR) provides a basic blur. - *
  • filter(GRAY) converts the image to grayscale based on luminance. - *
  • filter(INVERT) will invert the color components in the image. - *
  • filter(OPAQUE) set all the high bits in the image to opaque - *
  • filter(THRESHOLD) converts the image to black and white. - *
  • filter(DILATE) grow white/light areas - *
  • filter(ERODE) shrink white/light areas - *
- * Luminance conversion code contributed by - * toxi - *

- * Gaussian blur code contributed by - * Mario Klingemann - * - * @webref image:pixels - * @webBrief Converts the image to grayscale or black and white - * @usage web_application - * @param kind Either THRESHOLD, GRAY, OPAQUE, INVERT, POSTERIZE, BLUR, ERODE, or DILATE - * @param param unique for each, see above - */ + /** + * + * Filters the image as defined by one of the following modes:
+ *
+ * THRESHOLD
+ * Converts the image to black and white pixels depending if they are above or + * below the threshold defined by the level parameter. The parameter must be + * between 0.0 (black) and 1.0 (white). If no level is specified, 0.5 is + * used.
+ *
+ * GRAY
+ * Converts any colors in the image to grayscale equivalents. No parameter is + * used.
+ *
+ * OPAQUE
+ * Sets the alpha channel to entirely opaque. No parameter is used.
+ *
+ * INVERT
+ * Sets each pixel to its inverse value. No parameter is used.
+ *
+ * POSTERIZE
+ * Limits each channel of the image to the number of colors specified as the + * parameter. The parameter can be set to values between 2 and 255, but results + * are most noticeable in the lower ranges.
+ *
+ * BLUR
+ * Executes a Gaussian blur with the level parameter specifying the extent of + * the blurring. If no parameter is used, the blur is equivalent to Gaussian + * blur of radius 1. Larger values increase the blur.
+ *
+ * ERODE
+ * Reduces the light areas. No parameter is used.
+ *
+ * DILATE
+ * Increases the light areas. No parameter is used. + * + * + *

Advanced

Method to apply a variety of basic filters to this image. + *

+ *

    + *
  • filter(BLUR) provides a basic blur. + *
  • filter(GRAY) converts the image to grayscale based on luminance. + *
  • filter(INVERT) will invert the color components in the image. + *
  • filter(OPAQUE) set all the high bits in the image to opaque + *
  • filter(THRESHOLD) converts the image to black and white. + *
  • filter(DILATE) grow white/light areas + *
  • filter(ERODE) shrink white/light areas + *
+ * Luminance conversion code contributed by + * toxi + *

+ * Gaussian blur code contributed by + * Mario Klingemann + * + * @webref image:pixels + * @webBrief Converts the image to grayscale or black and white + * @usage web_application + * @param kind Either THRESHOLD, GRAY, OPAQUE, INVERT, POSTERIZE, BLUR, ERODE, + * or DILATE + * @param param unique for each, see above + */ public void filter(int kind, float param) { if (recorder != null) recorder.filter(kind, param); g.filter(kind, param); diff --git a/core/src/processing/core/PConstants.java b/core/src/processing/core/PConstants.java index d7069fb51..026c66319 100644 --- a/core/src/processing/core/PConstants.java +++ b/core/src/processing/core/PConstants.java @@ -127,41 +127,42 @@ public interface PConstants { // useful goodness - /** - * - * PI is a mathematical constant with the value 3.14159265358979323846. It - * is the ratio of the circumference of a circle to its diameter. It is - * useful in combination with the trigonometric functions sin() and - * cos(). - * - * @webref constants - * @webBrief PI is a mathematical constant with the value 3.14159265358979323846. - * @see PConstants#TWO_PI - * @see PConstants#TAU - * @see PConstants#HALF_PI - * @see PConstants#QUARTER_PI - * - */ + /** + * + * PI is a mathematical constant with the value 3.1415927. It is the + * ratio of the circumference of a circle to its diameter. It is useful in + * combination with the trigonometric functions sin() and cos(). + * + * @webref constants + * @webBrief PI is a mathematical constant with the value + * 3.14159265358979323846. + * @see PConstants#TWO_PI + * @see PConstants#TAU + * @see PConstants#HALF_PI + * @see PConstants#QUARTER_PI + * + */ static final float PI = (float) Math.PI; - /** - * - * HALF_PI is a mathematical constant with the value - * 1.57079632679489661923. It is half the ratio of the circumference of a - * circle to its diameter. It is useful in combination with the - * trigonometric functions sin() and cos(). - * - * @webref constants - * @webBrief HALF_PI is a mathematical constant with the value 1.57079632679489661923. - * @see PConstants#PI - * @see PConstants#TWO_PI - * @see PConstants#TAU - * @see PConstants#QUARTER_PI - */ + /** + * + * HALF_PI is a mathematical constant with the value 1.5707964. It is + * half the ratio of the circumference of a circle to its diameter. It is useful + * in combination with the trigonometric functions sin() and + * cos(). + * + * @webref constants + * @webBrief HALF_PI is a mathematical constant with the value + * 1.57079632679489661923. + * @see PConstants#PI + * @see PConstants#TWO_PI + * @see PConstants#TAU + * @see PConstants#QUARTER_PI + */ static final float HALF_PI = (float) (Math.PI / 2.0); static final float THIRD_PI = (float) (Math.PI / 3.0); /** * - * QUARTER_PI is a mathematical constant with the value 0.7853982. It is + * QUARTER_PI is a mathematical constant with the value 0.7853982. It is * one quarter the ratio of the circumference of a circle to its diameter. * It is useful in combination with the trigonometric functions * sin() and cos(). @@ -176,7 +177,7 @@ public interface PConstants { static final float QUARTER_PI = (float) (Math.PI / 4.0); /** * - * TWO_PI is a mathematical constant with the value 6.28318530717958647693. + * TWO_PI is a mathematical constant with the value 6.2831855. * It is twice the ratio of the circumference of a circle to its diameter. * It is useful in combination with the trigonometric functions * sin() and cos(). @@ -189,20 +190,21 @@ public interface PConstants { * @see PConstants#QUARTER_PI */ static final float TWO_PI = (float) (2.0 * Math.PI); - /** - * - * TAU is an alias for TWO_PI, a mathematical constant with the value - * 6.28318530717958647693. It is twice the ratio of the circumference - * of a circle to its diameter. It is useful in combination with the - * trigonometric functions sin() and cos(). - * - * @webref constants - * @webBrief An alias for TWO_PI - * @see PConstants#PI - * @see PConstants#TWO_PI - * @see PConstants#HALF_PI - * @see PConstants#QUARTER_PI - */ + /** + * + * TAU is a mathematical constant with the value 6.2831855. It is the + * circle constant relating the circumference of a circle to its linear + * dimension, the ratio of the circumference of a circle to its radius. It is + * useful in combination with trigonometric functions such as sin() and + * cos(). + * + * @webref constants + * @webBrief An alias for TWO_PI + * @see PConstants#PI + * @see PConstants#TWO_PI + * @see PConstants#HALF_PI + * @see PConstants#QUARTER_PI + */ static final float TAU = (float) (2.0 * Math.PI); static final float DEG_TO_RAD = PI/180.0f; diff --git a/core/src/processing/core/PFont.java b/core/src/processing/core/PFont.java index 7add0b020..8a7df97f6 100644 --- a/core/src/processing/core/PFont.java +++ b/core/src/processing/core/PFont.java @@ -35,9 +35,23 @@ import java.util.HashMap; /** - * Grayscale bitmap font class used by Processing. + * PFont is the font class for Processing. To create a font to use with + * Processing, select "Create Font..." from the Tools menu. This will create a + * font in the format Processing requires and also adds it to the current + * sketch's data directory. Processing displays fonts using the .vlw font + * format, which uses images for each letter, rather than defining them through + * vector data. The loadFont() function constructs a new font and + * textFont() makes a font active. The list() method creates a + * list of the fonts installed on the computer, which is useful information to + * use with the createFont() function for dynamically converting fonts + * into a format to use with Processing.
+ *
+ * To create a new font dynamically, use the createFont() function. Do + * not use the syntax new PFont(). + * *

* Awful (and by that, I mean awesome) ASCII (non-)art for how this works: + * * 

  *   |
  *   |                   height is the full used height of the image
@@ -55,6 +69,7 @@ import java.util.HashMap;
  *
  *   ^^^^^^^^^^^^^^ setWidth (width displaced by char)
  *
+ * * @webref typography * @webBrief Grayscale bitmap font class used by Processing. * @see PApplet#loadFont(String) @@ -869,20 +884,18 @@ public class PFont implements PConstants { } - /** - * - * Gets a list of the fonts installed on the system. The data is returned - * as a String array. This list provides the names of each font for input - * into createFont(), which allows Processing to dynamically format - * fonts. This function is meant as a tool for programming local - * applications and is not recommended for use in applets. - * - * - * @webref pfont - * @webBrief Gets a list of the fonts installed on the system. - * @usage application - * @brief Gets a list of the fonts installed on the system - */ + /** + * + * Gets a list of the fonts installed on the system. The data is returned as a + * String array. This list provides the names of each font for input into + * createFont(), which allows Processing to dynamically format fonts. + * + * + * @webref pfont + * @webBrief Gets a list of the fonts installed on the system. + * @usage application + * @brief Gets a list of the fonts installed on the system + */ static public String[] list() { loadFonts(); String[] list = new String[fonts.length]; diff --git a/core/src/processing/core/PGraphics.java b/core/src/processing/core/PGraphics.java index 570cee01b..452241aac 100644 --- a/core/src/processing/core/PGraphics.java +++ b/core/src/processing/core/PGraphics.java @@ -49,107 +49,108 @@ import java.util.concurrent.TimeUnit; import processing.opengl.PGL; import processing.opengl.PShader; - /** - * - * Main graphics and rendering context, as well as the base API - * implementation for processing "core". Use this class if you need to draw - * into an off-screen graphics buffer. A PGraphics object can be - * constructed with the createGraphics() function. The - * beginDraw() and endDraw() methods (see above example) are - * necessary to set up the buffer and to finalize it. The fields and - * methods for this class are extensive. For a complete list, visit the developer's reference. - * - * - *

Advanced

- * Main graphics and rendering context, as well as the base API implementation. - * - *

Subclassing and initializing PGraphics objects

- * Starting in release 0149, subclasses of PGraphics are handled differently. - * The constructor for subclasses takes no parameters, instead a series of - * functions are called by the hosting PApplet to specify its attributes. - *
    - *
  • setParent(PApplet) - is called to specify the parent PApplet. - *
  • setPrimary(boolean) - called with true if this PGraphics will be the - * primary drawing surface used by the sketch, or false if not. - *
  • setPath(String) - called when the renderer needs a filename or output - * path, such as with the PDF or DXF renderers. - *
  • setSize(int, int) - this is called last, at which point it's safe for - * the renderer to complete its initialization routine. - *
- * The functions were broken out because of the growing number of parameters - * such as these that might be used by a renderer, yet with the exception of - * setSize(), it's not clear which will be necessary. So while the size could - * be passed in to the constructor instead of a setSize() function, a function - * would still be needed that would notify the renderer that it was time to - * finish its initialization. Thus, setSize() simply does both. - * - *

Know your rights: public vs. private methods

- * Methods that are protected are often subclassed by other renderers, however - * they are not set 'public' because they shouldn't be part of the user-facing - * public API accessible from PApplet. That is, we don't want sketches calling - * textModeCheck() or vertexTexture() directly. - * - *

Handling warnings and exceptions

- * Methods that are unavailable generally show a warning, unless their lack of - * availability will soon cause another exception. For instance, if a method - * like getMatrix() returns null because it is unavailable, an exception will - * be thrown stating that the method is unavailable, rather than waiting for - * the NullPointerException that will occur when the sketch tries to use that - * method. As of release 0149, warnings will only be shown once, and exceptions - * have been changed to warnings where possible. - * - *

Using xxxxImpl() for subclassing smoothness

- * The xxxImpl() methods are generally renderer-specific handling for some - * subset if tasks for a particular function (vague enough for you?) For - * instance, imageImpl() handles drawing an image whose x/y/w/h and u/v coords - * have been specified, and screen placement (independent of imageMode) has - * been determined. There's no point in all renderers implementing the - * if (imageMode == BLAH) placement/sizing logic, so that's handled - * by PGraphics, which then calls imageImpl() once all that is figured out. - * - *

His brother PImage

- * PGraphics subclasses PImage so that it can be drawn and manipulated in a - * similar fashion. As such, many methods are inherited from PGraphics, - * though many are unavailable: for instance, resize() is not likely to be - * implemented; the same goes for mask(), depending on the situation. - * - *

What's in PGraphics, what ain't

- * For the benefit of subclasses, as much as possible has been placed inside - * PGraphics. For instance, bezier interpolation code and implementations of - * the strokeCap() method (that simply sets the strokeCap variable) are - * handled here. Features that will vary widely between renderers are located - * inside the subclasses themselves. For instance, all matrix handling code - * is per-renderer: Java 2D uses its own AffineTransform, P2D uses a PMatrix2D, - * and PGraphics3D needs to keep continually update forward and reverse - * transformations. A proper (future) OpenGL implementation will have all its - * matrix madness handled by the card. Lighting also falls under this - * category, however the base material property settings (emissive, specular, - * et al.) are handled in PGraphics because they use the standard colorMode() - * logic. Subclasses should override methods like emissiveFromCalc(), which - * is a point where a valid color has been defined internally, and can be - * applied in some manner based on the calcXxxx values. - * - *

What's in the PGraphics documentation, what ain't

- * Some things are noted here, some things are not. For public API, always - * refer to the reference - * on Processing.org for proper explanations. No attempt has been made to - * keep the javadoc up to date or complete. It's an enormous task for - * which we simply do not have the time. That is, it's not something that - * to be done once—it's a matter of keeping the multiple references - * synchronized (to say nothing of the translation issues), while targeting - * them for their separate audiences. Ouch. - * - * We're working right now on synchronizing the two references, so the website reference - * is generated from the javadoc comments. Yay. - * - * @webref rendering - * @webBrief Main graphics and rendering context, as well as the base API - * implementation for processing "core". - * @instanceName graphics any object of the type PGraphics - * @usage Web & Application - * @see PApplet#createGraphics(int, int, String) - */ + /** + * + * Main graphics and rendering context, as well as the base API implementation + * for processing "core". Use this class if you need to draw into an off-screen + * graphics buffer. A PGraphics object can be constructed with the + * createGraphics() function. The beginDraw() and endDraw() + * methods (see above example) are necessary to set up the buffer and to + * finalize it. The fields and methods for this class are extensive. For a + * complete list, visit the + * developer's + * reference.
+ *
+ * To create a new graphics context, use the createGraphics() function. + * Do not use the syntax new PGraphics(). + * + *

Advanced

Main graphics and rendering context, as well as the base + * API implementation. + * + *

Subclassing and initializing PGraphics objects

Starting in release + * 0149, subclasses of PGraphics are handled differently. The constructor for + * subclasses takes no parameters, instead a series of functions are called by + * the hosting PApplet to specify its attributes. + *
    + *
  • setParent(PApplet) - is called to specify the parent PApplet. + *
  • setPrimary(boolean) - called with true if this PGraphics will be the + * primary drawing surface used by the sketch, or false if not. + *
  • setPath(String) - called when the renderer needs a filename or output + * path, such as with the PDF or DXF renderers. + *
  • setSize(int, int) - this is called last, at which point it's safe for the + * renderer to complete its initialization routine. + *
+ * The functions were broken out because of the growing number of parameters + * such as these that might be used by a renderer, yet with the exception of + * setSize(), it's not clear which will be necessary. So while the size could be + * passed in to the constructor instead of a setSize() function, a function + * would still be needed that would notify the renderer that it was time to + * finish its initialization. Thus, setSize() simply does both. + * + *

Know your rights: public vs. private methods

Methods that are + * protected are often subclassed by other renderers, however they are not set + * 'public' because they shouldn't be part of the user-facing public API + * accessible from PApplet. That is, we don't want sketches calling + * textModeCheck() or vertexTexture() directly. + * + *

Handling warnings and exceptions

Methods that are unavailable + * generally show a warning, unless their lack of availability will soon cause + * another exception. For instance, if a method like getMatrix() returns null + * because it is unavailable, an exception will be thrown stating that the + * method is unavailable, rather than waiting for the NullPointerException that + * will occur when the sketch tries to use that method. As of release 0149, + * warnings will only be shown once, and exceptions have been changed to + * warnings where possible. + * + *

Using xxxxImpl() for subclassing smoothness

The xxxImpl() methods + * are generally renderer-specific handling for some subset if tasks for a + * particular function (vague enough for you?) For instance, imageImpl() handles + * drawing an image whose x/y/w/h and u/v coords have been specified, and screen + * placement (independent of imageMode) has been determined. There's no point in + * all renderers implementing the if (imageMode == BLAH) + * placement/sizing logic, so that's handled by PGraphics, which then calls + * imageImpl() once all that is figured out. + * + *

His brother PImage

PGraphics subclasses PImage so that it can be + * drawn and manipulated in a similar fashion. As such, many methods are + * inherited from PGraphics, though many are unavailable: for instance, resize() + * is not likely to be implemented; the same goes for mask(), depending on the + * situation. + * + *

What's in PGraphics, what ain't

For the benefit of subclasses, as + * much as possible has been placed inside PGraphics. For instance, bezier + * interpolation code and implementations of the strokeCap() method (that simply + * sets the strokeCap variable) are handled here. Features that will vary widely + * between renderers are located inside the subclasses themselves. For instance, + * all matrix handling code is per-renderer: Java 2D uses its own + * AffineTransform, P2D uses a PMatrix2D, and PGraphics3D needs to keep + * continually update forward and reverse transformations. A proper (future) + * OpenGL implementation will have all its matrix madness handled by the card. + * Lighting also falls under this category, however the base material property + * settings (emissive, specular, et al.) are handled in PGraphics because they + * use the standard colorMode() logic. Subclasses should override methods like + * emissiveFromCalc(), which is a point where a valid color has been defined + * internally, and can be applied in some manner based on the calcXxxx values. + * + *

What's in the PGraphics documentation, what ain't

Some things are + * noted here, some things are not. For public API, always refer to the + * reference on Processing.org for + * proper explanations. No attempt has been made to keep the javadoc up to + * date or complete. It's an enormous task for which we simply do not have + * the time. That is, it's not something that to be done once—it's a + * matter of keeping the multiple references synchronized (to say nothing of the + * translation issues), while targeting them for their separate audiences. Ouch. + * + * We're working right now on synchronizing the two references, so the website + * reference is generated from the javadoc comments. Yay. + * + * @webref rendering + * @webBrief Main graphics and rendering context, as well as the base API + * implementation for processing "core". + * @instanceName graphics any object of the type PGraphics + * @usage Web & Application + * @see PApplet#createGraphics(int, int, String) + */ public class PGraphics extends PImage implements PConstants { // /// Canvas object that covers rendering this graphics on screen. @@ -1190,43 +1191,44 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Using the beginShape() and endShape() functions allow - * creating more complex forms. beginShape() begins recording - * vertices for a shape and endShape() stops recording. The value of - * the MODE parameter tells it which types of shapes to create from - * the provided vertices. With no mode specified, the shape can be any - * irregular polygon. The parameters available for beginShape() are POINTS, - * LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, QUADS, and QUAD_STRIP. - * After calling the beginShape() function, a series of - * vertex() commands must follow. To stop drawing the shape, call - * endShape(). The vertex() function with two parameters - * specifies a position in 2D and the vertex() function with three - * parameters specifies a position in 3D. Each shape will be outlined with - * the current stroke color and filled with the fill color. - *

- * Transformations such as translate(), rotate(), and - * scale() do not work within beginShape(). It is also not - * possible to use other shapes, such as ellipse() or rect() - * within beginShape(). - *

- * The P3D renderer settings allow stroke() and fill() - * settings to be altered per-vertex, however the default P2D renderer does - * not. Settings such as strokeWeight(), strokeCap(), and - * strokeJoin() cannot be changed while inside a - * beginShape()/endShape() block with any renderer. - * - * @webref shape:vertex - * @webBrief Using the beginShape() and endShape() functions allow - * creating more complex forms. - * @param kind Either POINTS, LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, QUADS, or QUAD_STRIP - * @see PShape - * @see PGraphics#endShape() - * @see PGraphics#vertex(float, float, float, float, float) - * @see PGraphics#curveVertex(float, float, float) - * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, float, float) - */ + /** + * + * Using the beginShape() and endShape() functions allow creating + * more complex forms. beginShape() begins recording vertices for a shape + * and endShape() stops recording. The value of the kind parameter + * tells it which types of shapes to create from the provided vertices. With no + * mode specified, the shape can be any irregular polygon. The parameters + * available for beginShape() are POINTS, LINES, TRIANGLES, TRIANGLE_FAN, + * TRIANGLE_STRIP, QUADS, and QUAD_STRIP. After calling the beginShape() + * function, a series of vertex() commands must follow. To stop drawing + * the shape, call endShape(). The vertex() function with two + * parameters specifies a position in 2D and the vertex() function with + * three parameters specifies a position in 3D. Each shape will be outlined with + * the current stroke color and filled with the fill color.
+ *
+ * Transformations such as translate(), rotate(), and + * scale() do not work within beginShape(). It is also not + * possible to use other shapes, such as ellipse() or rect() + * within beginShape().
+ *
+ * The P2D and P3D renderers allow stroke() and fill() to be + * altered on a per-vertex basis, but the default renderer does not. Settings + * such as strokeWeight(), strokeCap(), and strokeJoin() + * cannot be changed while inside a beginShape()/endShape() block + * with any renderer. + * + * @webref shape:vertex + * @webBrief Using the beginShape() and endShape() functions allow + * creating more complex forms. + * @param kind Either POINTS, LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, + * QUADS, or QUAD_STRIP + * @see PShape + * @see PGraphics#endShape() + * @see PGraphics#vertex(float, float, float, float, float) + * @see PGraphics#curveVertex(float, float, float) + * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, + * float, float) + */ public void beginShape(int kind) { shape = kind; } @@ -1241,24 +1243,24 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the current normal vector. This is for drawing three dimensional - * shapes and surfaces and specifies a vector perpendicular to the surface - * of the shape which determines how lighting affects it. Processing - * attempts to automatically assign normals to shapes, but since that's - * imperfect, this is a better option when you want more control. This - * function is identical to glNormal3f() in OpenGL. - * - * @webref lights_camera:lights - * @webBrief Sets the current normal vector. - * @param nx x direction - * @param ny y direction - * @param nz z direction - * @see PGraphics#beginShape(int) - * @see PGraphics#endShape(int) - * @see PGraphics#lights() - */ + /** + * + * Sets the current normal vector. Used for drawing three dimensional shapes and + * surfaces, normal() specifies a vector perpendicular to a shape's + * surface which, in turn, determines how lighting affects it. Processing + * attempts to automatically assign normals to shapes, but since that's + * imperfect, this is a better option when you want more control. This function + * is identical to glNormal3f() in OpenGL. + * + * @webref lights_camera:lights + * @webBrief Sets the current normal vector. + * @param nx x direction + * @param ny y direction + * @param nz z direction + * @see PGraphics#beginShape(int) + * @see PGraphics#endShape(int) + * @see PGraphics#lights() + */ public void normal(float nx, float ny, float nz) { normalX = nx; normalY = ny; @@ -1308,22 +1310,23 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the coordinate space for texture mapping. There are two options, - * IMAGE, which refers to the actual coordinates of the image, and - * NORMAL, which refers to a normalized space of values ranging from 0 - * to 1. The default mode is IMAGE. In IMAGE, if an image is 100 x 200 - * pixels, mapping the image onto the entire size of a quad would require - * the points (0,0) (0,100) (100,200) (0,200). The same mapping in - * NORMAL_SPACE is (0,0) (0,1) (1,1) (0,1). - * - * @webref image:textures - * @webBrief Sets the coordinate space for texture mapping. - * @param mode either IMAGE or NORMAL - * @see PGraphics#texture(PImage) - * @see PGraphics#textureWrap(int) - */ + /** + * + * Sets the coordinate space for texture mapping. The default mode is + * IMAGE, which refers to the actual coordinates of the image. + * NORMAL refers to a normalized space of values ranging from 0 to 1. + * This function only works with the P2D and P3D renderers.
+ *
+ * With IMAGE, if an image is 100 x 200 pixels, mapping the image onto + * the entire size of a quad would require the points (0,0) (100, 0) (100,200) + * (0,200). The same mapping in NORMAL is (0,0) (1,0) (1,1) (0,1). + * + * @webref image:textures + * @webBrief Sets the coordinate space for texture mapping. + * @param mode either IMAGE or NORMAL + * @see PGraphics#texture(PImage) + * @see PGraphics#textureWrap(int) + */ public void textureMode(int mode) { if (mode != IMAGE && mode != NORMAL) { throw new RuntimeException("textureMode() only supports IMAGE and NORMAL"); @@ -1349,24 +1352,26 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets a texture to be applied to vertex points. The texture() - * function must be called between beginShape() and - * endShape() and before any calls to vertex(). - *

- * When textures are in use, the fill color is ignored. Instead, use tint() - * to specify the color of the texture as it is applied to the shape. - * - * @webref image:textures - * @webBrief Sets a texture to be applied to vertex points. - * @param image reference to a PImage object - * @see PGraphics#textureMode(int) - * @see PGraphics#textureWrap(int) - * @see PGraphics#beginShape(int) - * @see PGraphics#endShape(int) - * @see PGraphics#vertex(float, float, float, float, float) - */ + /** + * + * Sets a texture to be applied to vertex points. The texture() function + * must be called between beginShape() and endShape() and before + * any calls to vertex(). This function only works with the P2D and P3D + * renderers.
+ *
+ * When textures are in use, the fill color is ignored. Instead, use + * tint() to specify the color of the texture as it is applied to the + * shape. + * + * @webref image:textures + * @webBrief Sets a texture to be applied to vertex points. + * @param image reference to a PImage object + * @see PGraphics#textureMode(int) + * @see PGraphics#textureWrap(int) + * @see PGraphics#beginShape(int) + * @see PGraphics#endShape(int) + * @see PGraphics#vertex(float, float, float, float, float) + */ public void texture(PImage image) { textureImage = image; } @@ -1596,22 +1601,22 @@ public class PGraphics extends PImage implements PConstants { } /** - * - * All shapes are constructed by connecting a series of vertices. - * vertex() is used to specify the vertex coordinates for points, - * lines, triangles, quads, and polygons and is used exclusively within the - * beginShape() and endShape() function.
- *
- * Drawing a vertex in 3D using the z parameter requires the P3D - * parameter in combination with size as shown in the above example.
- *
- * This function is also used to map a texture onto the geometry. The - * texture() function declares the texture to apply to the geometry - * and the u and v coordinates set define the mapping of this - * texture to the form. By default, the coordinates used for u and - * v are specified in relation to the image's size in pixels, but - * this relation can be changed with textureMode(). - * + * + * All shapes are constructed by connecting a series of vertices. + * vertex() is used to specify the vertex coordinates for points, lines, + * triangles, quads, and polygons. It is used exclusively within the + * beginShape() and endShape() functions.
+ *
+ * Drawing a vertex in 3D using the z parameter requires the P3D + * parameter in combination with size, as shown in the above example.
+ *
+ * This function is also used to map a texture onto geometry. The + * texture() function declares the texture to apply to the geometry and + * the u and v coordinates set define the mapping of this texture + * to the form. By default, the coordinates used for u and v are + * specified in relation to the image's size in pixels, but this relation can be + * changed with textureMode(). + * * @webref shape:vertex * @webBrief All shapes are constructed by connecting a series of vertices. * @param x x-coordinate of the vertex @@ -1621,7 +1626,8 @@ public class PGraphics extends PImage implements PConstants { * @param v vertical coordinate for the texture mapping * @see PGraphics#beginShape(int) * @see PGraphics#endShape(int) - * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, float, float) + * @see PGraphics#bezierVertex(float, float, float, float, float, float, float, + * float, float) * @see PGraphics#quadraticVertex(float, float, float, float, float, float) * @see PGraphics#curveVertex(float, float, float) * @see PGraphics#texture(PImage) @@ -2518,22 +2524,33 @@ public class PGraphics extends PImage implements PConstants { // SIMPLE SHAPES WITH ANALOGUES IN beginShape() - /** - * - * Draws a point, a coordinate in space at the dimension of one pixel. The - * first parameter is the horizontal value for the point, the second value - * is the vertical value for the point, and the optional third value is the - * depth value. Drawing this shape in 3D with the z parameter - * requires the P3D parameter in combination with size() as shown in - * the above example. - * - * - * @webref shape:2d_primitives - * @webBrief Draws a point, a coordinate in space at the dimension of one pixel. - * @param x x-coordinate of the point - * @param y y-coordinate of the point - * @see PGraphics#stroke(int) - */ + /** + * + * Draws a point, a coordinate in space at the dimension of one pixel. The first + * parameter is the horizontal value for the point, the second value is the + * vertical value for the point, and the optional third value is the depth + * value. Drawing this shape in 3D with the z parameter requires the P3D + * parameter in combination with size() as shown in the above example. + *
+ *
+ * Use stroke() to set the color of a point().
+ *
+ * Point appears round with the default strokeCap(ROUND) and square with + * strokeCap(PROJECT). Points are invisible with strokeCap(SQUARE) + * (no cap).
+ *
+ * Using point() with strokeWeight(1) or smaller may draw nothing to the screen, + * depending on the graphics settings of the computer. Workarounds include + * setting the pixel using set() or drawing the point using either + * circle() or square(). + * + * + * @webref shape:2d_primitives + * @webBrief Draws a point, a coordinate in space at the dimension of one pixel. + * @param x x-coordinate of the point + * @param y y-coordinate of the point + * @see PGraphics#stroke(int) + */ public void point(float x, float y) { beginShape(POINTS); vertex(x, y); @@ -2652,52 +2669,66 @@ public class PGraphics extends PImage implements PConstants { // RECT - /** - * - * Modifies the location from which rectangles draw. The default mode is - * rectMode(CORNER), which specifies the location to be the upper - * left corner of the shape and uses the third and fourth parameters of - * rect() to specify the width and height. The syntax - * rectMode(CORNERS) uses the first and second parameters of - * rect() to set the location of one corner and uses the third and - * fourth parameters to set the opposite corner. The syntax - * rectMode(CENTER) draws the image from its center point and uses - * the third and forth parameters of rect() to specify the image's - * width and height. The syntax rectMode(RADIUS) draws the image - * from its center point and uses the third and forth parameters of - * rect() to specify half of the image's width and height. The - * parameter must be written in ALL CAPS because Processing is a case - * sensitive language. Note: In version 125, the mode named CENTER_RADIUS - * was shortened to RADIUS. - * - * @webref shape:attributes - * @webBrief Modifies the location from which rectangles draw. - * @param mode either CORNER, CORNERS, CENTER, or RADIUS - * @see PGraphics#rect(float, float, float, float) - */ + /** + * + * Modifies the location from which rectangles are drawn by changing the way in + * which parameters given to rect() are intepreted.
+ *
+ * The default mode is rectMode(CORNER), which interprets the first two + * parameters of rect() as the upper-left corner of the shape, while the + * third and fourth parameters are its width and height.
+ *
+ * rectMode(CORNERS) interprets the first two parameters of rect() + * as the location of one corner, and the third and fourth parameters as the + * location of the opposite corner.
+ *
+ * rectMode(CENTER) interprets the first two parameters of rect() + * as the shape's center point, while the third and fourth parameters are its + * width and height.
+ *
+ * rectMode(RADIUS) also uses the first two parameters of rect() + * as the shape's center point, but uses the third and fourth parameters to + * specify half of the shapes's width and height.
+ *
+ * The parameter must be written in ALL CAPS because Processing is a + * case-sensitive language. + * + * @webref shape:attributes + * @webBrief Modifies the location from which rectangles draw. + * @param mode either CORNER, CORNERS, CENTER, or RADIUS + * @see PGraphics#rect(float, float, float, float) + */ public void rectMode(int mode) { rectMode = mode; } - /** - * - * Draws a rectangle to the screen. A rectangle is a four-sided shape with - * every angle at ninety degrees. By default, the first two parameters set - * the location of the upper-left corner, the third sets the width, and the - * fourth sets the height. These parameters may be changed with the - * rectMode() function. - * - * - * @webref shape:2d_primitives - * @webBrief Draws a rectangle to the screen. - * @param a x-coordinate of the rectangle by default - * @param b y-coordinate of the rectangle by default - * @param c width of the rectangle by default - * @param d height of the rectangle by default - * @see PGraphics#rectMode(int) - * @see PGraphics#quad(float, float, float, float, float, float, float, float) - */ + /** + * + * Draws a rectangle to the screen. A rectangle is a four-sided shape with every + * angle at ninety degrees. By default, the first two parameters set the + * location of the upper-left corner, the third sets the width, and the fourth + * sets the height. The way these parameters are interpreted, however, may be + * changed with the rectMode() function.
+ *
+ * To draw a rounded rectangle, add a fifth parameter, which is used as the + * radius value for all four corners.
+ *
+ * To use a different radius value for each corner, include eight parameters. + * When using eight parameters, the latter four set the radius of the arc at + * each corner separately, starting with the top-left corner and moving + * clockwise around the rectangle. + * + * + * @webref shape:2d_primitives + * @webBrief Draws a rectangle to the screen. + * @param a x-coordinate of the rectangle by default + * @param b y-coordinate of the rectangle by default + * @param c width of the rectangle by default + * @param d height of the rectangle by default + * @see PGraphics#rectMode(int) + * @see PGraphics#quad(float, float, float, float, float, float, float, float) + */ public void rect(float a, float b, float c, float d) { float hradius, vradius; switch (rectMode) { @@ -2873,47 +2904,59 @@ public class PGraphics extends PImage implements PConstants { // ELLIPSE AND ARC - /** - * - * The origin of the ellipse is modified by the ellipseMode() - * function. The default configuration is ellipseMode(CENTER), which - * specifies the location of the ellipse as the center of the shape. The - * RADIUS mode is the same, but the width and height parameters to - * ellipse() specify the radius of the ellipse, rather than the - * diameter. The CORNER mode draws the shape from the upper-left - * corner of its bounding box. The CORNERS mode uses the four - * parameters to ellipse() to set two opposing corners of the - * ellipse's bounding box. The parameter must be written in ALL CAPS - * because Processing is a case-sensitive language. - * - * @webref shape:attributes - * @webBrief The origin of the ellipse is modified by the ellipseMode() - * function. - * @param mode either CENTER, RADIUS, CORNER, or CORNERS - * @see PApplet#ellipse(float, float, float, float) - * @see PApplet#arc(float, float, float, float, float, float) - */ + /** + * + * Modifies the location from which ellipses are drawn by changing the way in + * which parameters given to ellipse() are intepreted.
+ *
+ * The default mode is ellipseMode(CENTER), which interprets the first + * two parameters of ellipse() as the shape's center point, while the + * third and fourth parameters are its width and height.
+ *
+ * ellipseMode(RADIUS) also uses the first two parameters of + * ellipse() as the shape's center point, but uses the third and fourth + * parameters to specify half of the shapes's width and height.
+ *
+ * ellipseMode(CORNER) interprets the first two parameters of + * ellipse() as the upper-left corner of the shape, while the third and + * fourth parameters are its width and height.
+ *
+ * ellipseMode(CORNERS) interprets the first two parameters of + * ellipse() as the location of one corner of the ellipse's bounding box, + * and the third and fourth parameters as the location of the opposite + * corner.
+ *
+ * The parameter must be written in ALL CAPS because Processing is a + * case-sensitive language. + * + * @webref shape:attributes + * @webBrief The origin of the ellipse is modified by the ellipseMode() + * function. + * @param mode either CENTER, RADIUS, CORNER, or CORNERS + * @see PApplet#ellipse(float, float, float, float) + * @see PApplet#arc(float, float, float, float, float, float) + */ public void ellipseMode(int mode) { ellipseMode = mode; } - /** - * - * Draws an ellipse (oval) in the display window. An ellipse with an equal - * width and height is a circle. The first two parameters set - * the location, the third sets the width, and the fourth sets the height. - * The origin may be changed with the ellipseMode() function. - * - * @webref shape:2d_primitives - * @webBrief Draws an ellipse (oval) in the display window. - * @param a x-coordinate of the ellipse - * @param b y-coordinate of the ellipse - * @param c width of the ellipse by default - * @param d height of the ellipse by default - * @see PApplet#ellipseMode(int) - * @see PApplet#arc(float, float, float, float, float, float) - */ + /** + * + * Draws an ellipse (oval) to the screen. An ellipse with equal width and height + * is a circle. By default, the first two parameters set the location, and the + * third and fourth parameters set the shape's width and height. The origin may + * be changed with the ellipseMode() function. + * + * @webref shape:2d_primitives + * @webBrief Draws an ellipse (oval) in the display window. + * @param a x-coordinate of the ellipse + * @param b y-coordinate of the ellipse + * @param c width of the ellipse by default + * @param d height of the ellipse by default + * @see PApplet#ellipseMode(int) + * @see PApplet#arc(float, float, float, float, float, float) + */ public void ellipse(float a, float b, float c, float d) { float x = a; float y = b; @@ -2953,27 +2996,38 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Draws an arc in the display window. Arcs are drawn along the outer edge - * of an ellipse defined by the x, y, width and - * height parameters. The origin or the arc's ellipse may be changed - * with the ellipseMode() function. The start and stop - * parameters specify the angles at which to draw the arc. - * - * @webref shape:2d_primitives - * @webBrief Draws an arc in the display window. - * @param a x-coordinate of the arc's ellipse - * @param b y-coordinate of the arc's ellipse - * @param c width of the arc's ellipse by default - * @param d height of the arc's ellipse by default - * @param start angle to start the arc, specified in radians - * @param stop angle to stop the arc, specified in radians - * @see PApplet#ellipse(float, float, float, float) - * @see PApplet#ellipseMode(int) - * @see PApplet#radians(float) - * @see PApplet#degrees(float) - */ + /** + * + * Draws an arc to the screen. Arcs are drawn along the outer edge of an ellipse + * defined by the a, b, c, and d parameters. The + * origin of the arc's ellipse may be changed with the ellipseMode() + * function. Use the start and stop parameters to specify the + * angles (in radians) at which to draw the arc. The start/stop values must be + * in clockwise order.
+ *
+ * There are three ways to draw an arc; the rendering technique used is defined + * by the optional seventh parameter. The three options, depicted in the above + * examples, are PIE, OPEN, and CHORD. The default mode is the OPEN stroke with + * a PIE fill.
+ *
+ * In some cases, the arc() function isn't accurate enough for smooth + * drawing. For example, the shape may jitter on screen when rotating slowly. If + * you're having an issue with how arcs are rendered, you'll need to draw the + * arc yourself with beginShape()/endShape() or a PShape. + * + * @webref shape:2d_primitives + * @webBrief Draws an arc in the display window. + * @param a x-coordinate of the arc's ellipse + * @param b y-coordinate of the arc's ellipse + * @param c width of the arc's ellipse by default + * @param d height of the arc's ellipse by default + * @param start angle to start the arc, specified in radians + * @param stop angle to stop the arc, specified in radians + * @see PApplet#ellipse(float, float, float, float) + * @see PApplet#ellipseMode(int) + * @see PApplet#radians(float) + * @see PApplet#degrees(float) + */ public void arc(float a, float b, float c, float d, float start, float stop) { arc(a, b, c, d, start, stop, 0); @@ -3412,20 +3466,21 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the resolution at which Beziers display. The default value is 20. - * This function is only useful when using the P3D renderer as the default - * P2D renderer does not use this information. - * - * - * @webref shape:curves - * @webBrief Sets the resolution at which Beziers display. - * @param detail resolution of the curves - * @see PGraphics#curve(float, float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#curveVertex(float, float, float) - * @see PGraphics#curveTightness(float) - */ + /** + * + * Sets the resolution at which Beziers display. The default value is 20. This + * function is only useful when using the P3D renderer; the default + * P2D renderer does not use this information. + * + * + * @webref shape:curves + * @webBrief Sets the resolution at which Beziers display. + * @param detail resolution of the curves + * @see PGraphics#curve(float, float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#curveVertex(float, float, float) + * @see PGraphics#curveTightness(float) + */ public void bezierDetail(int detail) { bezierDetail = detail; @@ -3525,25 +3580,29 @@ public class PGraphics extends PImage implements PConstants { // CATMULL-ROM CURVE - /** - * - * Evalutes the curve at point t for points a, b, c, d. The parameter t - * varies between 0 and 1, a and d are the control points, and b and c are - * the points on the curve. This can be done once with the x coordinates and a - * second time with the y coordinates to get the location of a curve at t. - * - * - * @webref shape:curves - * @webBrief Evalutes the curve at point t for points a, b, c, d. - * @param a coordinate of first control point - * @param b coordinate of first point on the curve - * @param c coordinate of second point on the curve - * @param d coordinate of second control point - * @param t value between 0 and 1 - * @see PGraphics#curve(float, float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#curveVertex(float, float) - * @see PGraphics#bezierPoint(float, float, float, float, float) - */ + /** + * + * Evaluates the curve at point t for points a, b, + * c, d. The parameter t may range from 0 (the start of the + * curve) and 1 (the end of the curve). a and d are the control + * points, and b and c are points on the curve. As seen in the + * example above, this can be used once with the x coordinates and a + * second time with the y coordinates to get the location of a curve at + * t. + * + * + * @webref shape:curves + * @webBrief Evalutes the curve at point t for points a, b, c, d. + * @param a coordinate of first control point + * @param b coordinate of first point on the curve + * @param c coordinate of second point on the curve + * @param d coordinate of second control point + * @param t value between 0 and 1 + * @see PGraphics#curve(float, float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#curveVertex(float, float) + * @see PGraphics#bezierPoint(float, float, float, float, float) + */ public float curvePoint(float a, float b, float c, float d, float t) { curveInitCheck(); @@ -3616,24 +3675,25 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Modifies the quality of forms created with curve() and - * curveVertex(). The parameter squishy determines how the - * curve fits to the vertex points. The value 0.0 is the default value for - * squishy (this value defines the curves to be Catmull-Rom splines) - * and the value 1.0 connects all the points with straight lines. Values - * within the range -5.0 and 5.0 will deform the curves but will leave them - * recognizable and as values increase in magnitude, they will continue to deform. - * - * - * @webref shape:curves - * @webBrief Modifies the quality of forms created with curve() and - * curveVertex(). - * @param tightness amount of deformation from the original vertices - * @see PGraphics#curve(float, float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#curveVertex(float, float) - */ + /** + * + * Modifies the quality of forms created with curve() and + * curveVertex(). The parameter tightness determines how the curve + * fits to the vertex points. The value 0.0 is the default value for + * tightness (this value defines the curves to be Catmull-Rom splines) + * and the value 1.0 connects all the points with straight lines. Values within + * the range -5.0 and 5.0 will deform the curves but will leave them + * recognizable and as values increase in magnitude, they will continue to + * deform. + * + * @webref shape:curves + * @webBrief Modifies the quality of forms created with curve() and + * curveVertex(). + * @param tightness amount of deformation from the original vertices + * @see PGraphics#curve(float, float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#curveVertex(float, float) + */ public void curveTightness(float tightness) { curveTightness = tightness; curveInit(); @@ -3836,30 +3896,36 @@ public class PGraphics extends PImage implements PConstants { // IMAGE - /** - * - * Modifies the location from which images draw. The default mode is - * imageMode(CORNER), which specifies the location to be the upper - * left corner and uses the fourth and fifth parameters of image() - * to set the image's width and height. The syntax - * imageMode(CORNERS) uses the second and third parameters of - * image() to set the location of one corner of the image and uses - * the fourth and fifth parameters to set the opposite corner. Use - * imageMode(CENTER) to draw images centered at the given x and y - * position.
- *
- * The parameter to imageMode() must be written in ALL CAPS because - * Processing is a case-sensitive language. - * - * - * @webref image:loading_displaying - * @webBrief Modifies the location from which images draw. - * @param mode either CORNER, CORNERS, or CENTER - * @see PApplet#loadImage(String, String) - * @see PImage - * @see PGraphics#image(PImage, float, float, float, float) - * @see PGraphics#background(float, float, float, float) - */ + /** + * + * Modifies the location from which images are drawn by changing the way in + * which parameters given to image() are intepreted.
+ *
+ * The default mode is imageMode(CORNER), which interprets the second and + * third parameters of image() as the upper-left corner of the image. If + * two additional parameters are specified, they are used to set the image's + * width and height.
+ *
+ * imageMode(CORNERS) interprets the second and third parameters of + * image() as the location of one corner, and the fourth and fifth + * parameters as the opposite corner.
+ *
+ * imageMode(CENTER) interprets the second and third parameters of + * image() as the image's center point. If two additional parameters are + * specified, they are used to set the image's width and height.
+ *
+ * The parameter must be written in ALL CAPS because Processing is a + * case-sensitive language. + * + * + * @webref image:loading_displaying + * @webBrief Modifies the location from which images draw. + * @param mode either CORNER, CORNERS, or CENTER + * @see PApplet#loadImage(String, String) + * @see PImage + * @see PGraphics#image(PImage, float, float, float, float) + * @see PGraphics#background(float, float, float, float) + */ public void imageMode(int mode) { if ((mode == CORNER) || (mode == CORNERS) || (mode == CENTER)) { imageMode = mode; @@ -3871,42 +3937,38 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Displays images to the screen. The images must be in the sketch's "data" - * directory to load correctly. Select "Add file..." from the "Sketch" menu - * to add the image. Processing currently works with GIF, JPEG, and Targa - * images. The img parameter specifies the image to display and the - * x and y parameters define the location of the image from - * its upper-left corner. The image is displayed at its original size - * unless the width and height parameters specify a different - * size.
- *
- * The imageMode() function changes the way the parameters work. For - * example, a call to imageMode(CORNERS) will change the - * width and height parameters to define the x and y values - * of the opposite corner of the image.
- *
- * The color of an image may be modified with the tint() function. - * This function will maintain transparency for GIF and PNG images. - * - * - *

Advanced

- * Starting with release 0124, when using the default (JAVA2D) renderer, - * smooth() will also improve image quality of resized images. - * - * @webref image:loading_displaying - * @webBrief Displays images to the screen. - * @param img the image to display - * @param a x-coordinate of the image by default - * @param b y-coordinate of the image by default - * @see PApplet#loadImage(String, String) - * @see PImage - * @see PGraphics#imageMode(int) - * @see PGraphics#tint(float) - * @see PGraphics#background(float, float, float, float) - * @see PGraphics#alpha(int) - */ + /** + * + * The image() function draws an image to the display window. Images must + * be in the sketch's "data" directory to load correctly. Select "Add file..." + * from the "Sketch" menu to add the image to the data directory, or just drag + * the image file onto the sketch window. Processing currently works with GIF, + * JPEG, and PNG images.
+ *
+ * The img parameter specifies the image to display and by default the + * a and b parameters define the location of its upper-left + * corner. The image is displayed at its original size unless the c and + * d parameters specify a different size. The imageMode() function + * can be used to change the way these parameters draw the image.
+ *
+ * The color of an image may be modified with the tint() function. This + * function will maintain transparency for GIF and PNG images. + * + *

Advanced

Starting with release 0124, when using the default (JAVA2D) + * renderer, smooth() will also improve image quality of resized images. + * + * @webref image:loading_displaying + * @webBrief Displays images to the screen. + * @param img the image to display + * @param a x-coordinate of the image by default + * @param b y-coordinate of the image by default + * @see PApplet#loadImage(String, String) + * @see PImage + * @see PGraphics#imageMode(int) + * @see PGraphics#tint(float) + * @see PGraphics#background(float, float, float, float) + * @see PGraphics#alpha(int) + */ public void image(PImage img, float a, float b) { // Starting in release 0144, image errors are simply ignored. // loadImageAsync() sets width and height to -1 when loading fails. @@ -4100,35 +4162,29 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Displays shapes to the screen. The shapes must be in the sketch's "data" - * directory to load correctly. Select "Add file..." from the "Sketch" menu - * to add the shape. Processing currently works with SVG shapes only. The - * sh parameter specifies the shape to display and the x and - * y parameters define the location of the shape from its upper-left - * corner. The shape is displayed at its original size unless the - * width and height parameters specify a different size. The - * shapeMode() function changes the way the parameters work. A call - * to shapeMode(CORNERS), for example, will change the width and - * height parameters to define the x and y values of the opposite corner of - * the shape. - *

- * Note complex shapes may draw awkwardly with P3D. This renderer does not - * yet support shapes that have holes or complicated breaks. - * - * - * @webref shape:loading_displaying - * @webBrief Displays shapes to the screen. - * @param shape the shape to display - * @param x x-coordinate of the shape - * @param y y-coordinate of the shape - * @see PShape - * @see PApplet#loadShape(String) - * @see PGraphics#shapeMode(int) - * - * Convenience method to draw at a particular location. - */ + /** + * + * Draws shapes to the display window. Shapes must be in the sketch's "data" + * directory to load correctly. Select "Add file..." from the "Sketch" menu to + * add the shape. Processing currently works with SVG, OBJ, and custom-created + * shapes. The shape parameter specifies the shape to display and the + * coordinate parameters define the location of the shape from its upper-left + * corner. The shape is displayed at its original size unless the c and + * d parameters specify a different size. The shapeMode() function + * can be used to change the way these parameters are interpreted. + * + * + * @webref shape:loading_displaying + * @webBrief Displays shapes to the screen. + * @param shape the shape to display + * @param x x-coordinate of the shape + * @param y y-coordinate of the shape + * @see PShape + * @see PApplet#loadShape(String) + * @see PGraphics#shapeMode(int) + * + * Convenience method to draw at a particular location. + */ public void shape(PShape shape, float x, float y) { if (shape.isVisible()) { // don't do expensive matrix ops if invisible flush(); @@ -4255,63 +4311,61 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the current alignment for drawing text. The parameters LEFT, - * CENTER, and RIGHT set the display characteristics of the letters in - * relation to the values for the x and y parameters of the - * text() function. - *

- * In Processing 0125 and later, an optional second parameter can be used - * to vertically align the text. BASELINE is the default, and the vertical - * alignment will be reset to BASELINE if the second parameter is not used. - * The TOP and CENTER parameters are straightforward. The BOTTOM parameter - * offsets the line based on the current textDescent(). For multiple - * lines, the final line will be aligned to the bottom, with the previous - * lines appearing above it. - *

- * When using text() with width and height parameters, BASELINE is - * ignored, and treated as TOP. (Otherwise, text would by default draw - * outside the box, since BASELINE is the default setting. BASELINE is not - * a useful drawing mode for text drawn in a rectangle.) - *

- * The vertical alignment is based on the value of textAscent(), - * which many fonts do not specify correctly. It may be necessary to use a - * hack and offset by a few pixels by hand so that the offset looks - * correct. To do this as less of a hack, use some percentage of - * textAscent() or textDescent() so that the hack works even - * if you change the size of the font. - * - * - * @webref typography:attributes - * @webBrief Sets the current alignment for drawing text. - * @param alignX horizontal alignment, either LEFT, CENTER, or RIGHT - * @param alignY vertical alignment, either TOP, BOTTOM, CENTER, or BASELINE - * @see PApplet#loadFont(String) - * @see PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textSize(float) - * @see PGraphics#textAscent() - * @see PGraphics#textDescent() - */ + /** + * + * Sets the current alignment for drawing text. The parameters LEFT, CENTER, and + * RIGHT set the display characteristics of the letters in relation to the + * values for the x and y parameters of the text() + * function.
+ *
+ * An optional second parameter can be used to vertically align the text. + * BASELINE is the default, and the vertical alignment will be reset to BASELINE + * if the second parameter is not used. The TOP and CENTER parameters are + * straightforward. The BOTTOM parameter offsets the line based on the current + * textDescent(). For multiple lines, the final line will be aligned to + * the bottom, with the previous lines appearing above it.
+ *
+ * When using text() with width and height parameters, BASELINE is + * ignored, and treated as TOP. (Otherwise, text would by default draw outside + * the box, since BASELINE is the default setting. BASELINE is not a useful + * drawing mode for text drawn in a rectangle.)
+ *
+ * The vertical alignment is based on the value of textAscent(), which + * many fonts do not specify correctly. It may be necessary to use a hack and + * offset by a few pixels by hand so that the offset looks correct. To do this + * as less of a hack, use some percentage of textAscent() or + * textDescent() so that the hack works even if you change the size of + * the font. + * + * + * + * @webref typography:attributes + * @webBrief Sets the current alignment for drawing text. + * @param alignX horizontal alignment, either LEFT, CENTER, or RIGHT + * @param alignY vertical alignment, either TOP, BOTTOM, CENTER, or BASELINE + * @see PApplet#loadFont(String) + * @see PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textSize(float) + * @see PGraphics#textAscent() + * @see PGraphics#textDescent() + */ public void textAlign(int alignX, int alignY) { textAlign = alignX; textAlignY = alignY; } - /** - * - * Returns ascent of the current font at its current size. This information - * is useful for determining the height of the font above the baseline. For - * example, adding the textAscent() and textDescent() values - * will give you the total height of the line. - * - * - * @webref typography:metrics - * @webBrief Returns ascent of the current font at its current size. - * @see PGraphics#textDescent() - */ + /** + * + * Returns ascent of the current font at its current size. This information is + * useful for determining the height of the font above the baseline. + * + * + * @webref typography:metrics + * @webBrief Returns ascent of the current font at its current size. + * @see PGraphics#textDescent() + */ public float textAscent() { if (textFont == null) { defaultFontOrDeath("textAscent"); @@ -4320,18 +4374,15 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Returns descent of the current font at its current size. This - * information is useful for determining the height of the font below the - * baseline. For example, adding the textAscent() and - * textDescent() values will give you the total height of the line. - * - * - * @webref typography:metrics - * @webBrief Returns descent of the current font at its current size. - * @see PGraphics#textAscent() - */ + /** + * + * Returns descent of the current font at its current size. This information is + * useful for determining the height of the font below the baseline. + * + * @webref typography:metrics + * @webBrief Returns descent of the current font at its current size. + * @see PGraphics#textAscent() + */ public float textDescent() { if (textFont == null) { defaultFontOrDeath("textDescent"); @@ -4340,35 +4391,35 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the current font that will be drawn with the text() - * function. Fonts must be loaded with loadFont() before it can be - * used. This font will be used in all subsequent calls to the - * text() function. If no size parameter is input, the font - * will appear at its original size (the size it was created at with the - * "Create Font..." tool) until it is changed with textSize().

Because fonts are usually bitmaped, you should create fonts at - * the sizes that will be used most commonly. Using textFont() - * without the size parameter will result in the cleanest-looking text.

With the default (JAVA2D) and PDF renderers, it's also possible - * to enable the use of native fonts via the command - * hint(ENABLE_NATIVE_FONTS). This will produce vector text in - * JAVA2D sketches and PDF output in cases where the vector data is - * available: when the font is still installed, or the font is created via - * the createFont() function (rather than the Create Font tool). - * - * - * @webref typography:loading_displaying - * @webBrief Sets the current font that will be drawn with the text() - * function. - * @param which any variable of the type PFont - * @see PApplet#createFont(String, float, boolean) - * @see PApplet#loadFont(String) - * @see PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textSize(float) - */ + /** + * + * Sets the current font that will be drawn with the text() function. + * Fonts must be created for Processing with createFont() or loaded with + * loadFont() before they can be used. The font set through + * textFont() will be used in all subsequent calls to the text() + * function. If no size parameter is specified, the font size defaults to + * the original size (the size in which it was created with the "Create Font..." + * tool) overriding any previous calls to textFont() or + * textSize().
+ *
+ * When fonts are rendered as an image texture (as is the case with the P2D and + * P3D renderers as well as with loadFont() and vlw files), you should + * create fonts at the sizes that will be used most commonly. Using + * textFont() without the size parameter will result in the cleanest + * type.
+ *
+ * + * + * @webref typography:loading_displaying + * @webBrief Sets the current font that will be drawn with the text() + * function. + * @param which any variable of the type PFont + * @see PApplet#createFont(String, float, boolean) + * @see PApplet#loadFont(String) + * @see PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textSize(float) + */ public void textFont(PFont which) { if (which == null) { throw new RuntimeException(ERROR_TEXTFONT_NULL_PFONT); @@ -4440,57 +4491,58 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the spacing between lines of text in units of pixels. This setting - * will be used in all subsequent calls to the text() function. - * - * - * @webref typography:attributes - * @webBrief Sets the spacing between lines of text in units of pixels. - * @param leading the size in pixels for spacing between lines - * @see PApplet#loadFont(String) - * @see PFont#PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textFont(PFont) - * @see PGraphics#textSize(float) - */ + /** + * + * Sets the spacing between lines of text in units of pixels. This setting will + * be used in all subsequent calls to the text() function. Note, however, + * that the leading is reset by textSize(). For example, if the leading + * is set to 20 with textLeading(20), then if textSize(48) is run + * at a later point, the leading will be reset to the default for the text size + * of 48. + * + * + * @webref typography:attributes + * @webBrief Sets the spacing between lines of text in units of pixels. + * @param leading the size in pixels for spacing between lines + * @see PApplet#loadFont(String) + * @see PFont#PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textFont(PFont) + * @see PGraphics#textSize(float) + */ public void textLeading(float leading) { textLeading = leading; } - /** - * - * Sets the way text draws to the screen. In the default configuration, the - * MODEL mode, it's possible to rotate, scale, and place letters in - * two and three dimensional space.
- *
- * The SHAPE mode draws text using the the glyph outlines of - * individual characters rather than as textures. This mode is only - * supported with the PDF and P3D renderer settings. With the - * PDF renderer, you must call textMode(SHAPE) before any - * other drawing occurs. If the outlines are not available, then - * textMode(SHAPE) will be ignored and textMode(MODEL) will - * be used instead.
- *
- * The textMode(SHAPE) option in P3D can be combined with - * beginRaw() to write vector-accurate text to 2D and 3D output - * files, for instance DXF or PDF. The SHAPE mode is - * not currently optimized for P3D, so if recording shape data, use - * textMode(MODEL) until you're ready to capture the geometry with beginRaw(). - * - * - * @webref typography:attributes - * @webBrief Sets the way text draws to the screen. - * @param mode either MODEL or SHAPE - * @see PApplet#loadFont(String) - * @see PFont#PFont - * @see PGraphics#text(String, float, float) - * @see PGraphics#textFont(PFont) - * @see PGraphics#beginRaw(PGraphics) - * @see PApplet#createFont(String, float, boolean) - */ + /** + * + * Sets the way text draws to the screen, either as texture maps or as vector + * geometry. The default textMode(MODEL), uses textures to render the + * fonts. The textMode(SHAPE) mode draws text using the glyph outlines of + * individual characters rather than as textures. This mode is only supported + * with the PDF and P3D renderer settings. With the PDF + * renderer, you must call textMode(SHAPE) before any other drawing + * occurs. If the outlines are not available, then textMode(SHAPE) will + * be ignored and textMode(MODEL) will be used instead.
+ *
+ * The textMode(SHAPE) option in P3D can be combined with + * beginRaw() to write vector-accurate text to 2D and 3D output files, + * for instance DXF or PDF. The SHAPE mode is not currently + * optimized for P3D, so if recording shape data, use + * textMode(MODEL) until you're ready to capture the geometry with + * beginRaw(). + * + * @webref typography:attributes + * @webBrief Sets the way text draws to the screen. + * @param mode either MODEL or SHAPE + * @see PApplet#loadFont(String) + * @see PFont#PFont + * @see PGraphics#text(String, float, float) + * @see PGraphics#textFont(PFont) + * @see PGraphics#beginRaw(PGraphics) + * @see PApplet#createFont(String, float, boolean) + */ public void textMode(int mode) { // CENTER and MODEL overlap (they're both 3) if ((mode == LEFT) || (mode == RIGHT)) { @@ -4654,40 +4706,45 @@ public class PGraphics extends PImage implements PConstants { // ........................................................ - /** - * - * Draws text to the screen. Displays the information specified in the - * data or stringdata parameters on the screen in the - * position specified by the x and y parameters and the - * optional z parameter. A default font will be used unless a font - * is set with the textFont() function. Change the color of the text - * with the fill() function. The text displays in relation to the - * textAlign() function, which gives the option to draw to the left, - * right, and center of the coordinates. - *

- * The x2 and y2 parameters define a rectangular area to - * display within and may only be used with string data. For text drawn - * inside a rectangle, the coordinates are interpreted based on the current - * rectMode() setting. - * - * - * @webref typography:loading_displaying - * @webBrief Draws text to the screen. - * @param c the alphanumeric character to be displayed - * @param x x-coordinate of text - * @param y y-coordinate of text - * @see PGraphics#textAlign(int, int) - * @see PGraphics#textFont(PFont) - * @see PGraphics#textMode(int) - * @see PGraphics#textSize(float) - * @see PGraphics#textLeading(float) - * @see PGraphics#textWidth(String) - * @see PGraphics#textAscent() - * @see PGraphics#textDescent() - * @see PGraphics#rectMode(int) - * @see PGraphics#fill(int, float) - * @see_external String - */ + /** + * + * Draws text to the screen. Displays the information specified in the first + * parameter on the screen in the position specified by the additional + * parameters. A default font will be used unless a font is set with the + * textFont() function and a default size will be used unless a font is + * set with textSize(). Change the color of the text with the + * fill() function. The text displays in relation to the + * textAlign() function, which gives the option to draw to the left, + * right, and center of the coordinates.
+ *
+ * The x2 and y2 parameters define a rectangular area to display + * within and may only be used with string data. When these parameters are + * specified, they are interpreted based on the current rectMode() + * setting. Text that does not fit completely within the rectangle specified + * will not be drawn to the screen.
+ *
+ * Note that Processing now lets you call text() without first specifying + * a PFont with textFont(). In that case, a generic sans-serif font will + * be used instead. (See the third example above.) + * + * + * @webref typography:loading_displaying + * @webBrief Draws text to the screen. + * @param c the alphanumeric character to be displayed + * @param x x-coordinate of text + * @param y y-coordinate of text + * @see PGraphics#textAlign(int, int) + * @see PGraphics#textFont(PFont) + * @see PGraphics#textMode(int) + * @see PGraphics#textSize(float) + * @see PGraphics#textLeading(float) + * @see PGraphics#textWidth(String) + * @see PGraphics#textAscent() + * @see PGraphics#textDescent() + * @see PGraphics#rectMode(int) + * @see PGraphics#fill(int, float) + * @see_external String + */ public void text(char c, float x, float y) { if (textFont == null) { defaultFontOrDeath("text"); @@ -5298,7 +5355,7 @@ public class PGraphics extends PImage implements PConstants { * Note that these functions are always used together. They allow * you to change the style and transformation settings and later * return to what you had. When a new state is started with push(), - * it builds on the current style and transform information.
+ * it builds on the current style and transform information. *
*
* push() stores information related to the current @@ -5388,34 +5445,36 @@ public class PGraphics extends PImage implements PConstants { // MATRIX TRANSFORMATIONS - /** - * - * Specifies an amount to displace objects within the display window. The - * x parameter specifies left/right translation, the y - * parameter specifies up/down translation, and the z parameter - * specifies translations toward/away from the screen. Using this function - * with the z parameter requires using P3D as a parameter in - * combination with size as shown in the above example. Transformations - * apply to everything that happens after and subsequent calls to the - * function accumulates the effect. For example, calling translate(50, - * 0) and then translate(20, 0) is the same as translate(70, - * 0). If translate() is called within draw(), the - * transformation is reset when the loop begins again. This function can be - * further controlled by the pushMatrix() and popMatrix(). - * - * - * @webref transform - * @webBrief Specifies an amount to displace objects within the display window. - * @param x left/right translation - * @param y up/down translation - * @see PGraphics#popMatrix() - * @see PGraphics#pushMatrix() - * @see PGraphics#rotate(float) - * @see PGraphics#rotateX(float) - * @see PGraphics#rotateY(float) - * @see PGraphics#rotateZ(float) - * @see PGraphics#scale(float, float, float) - */ + /** + * + * Specifies an amount to displace objects within the display window. The + * x parameter specifies left/right translation, the y parameter + * specifies up/down translation, and the z parameter specifies + * translations toward/away from the screen. Using this function with the + * z parameter requires using P3D as a parameter in combination with size + * as shown in the above example.
+ *
+ * Transformations are cumulative and apply to everything that happens after and + * subsequent calls to the function accumulates the effect. For example, calling + * translate(50, 0) and then translate(20, 0) is the same as + * translate(70, 0). If translate() is called within + * draw(), the transformation is reset when the loop begins again. This + * function can be further controlled by using pushMatrix() and + * popMatrix(). + * + * + * @webref transform + * @webBrief Specifies an amount to displace objects within the display window. + * @param x left/right translation + * @param y up/down translation + * @see PGraphics#popMatrix() + * @see PGraphics#pushMatrix() + * @see PGraphics#rotate(float) + * @see PGraphics#rotateX(float) + * @see PGraphics#rotateY(float) + * @see PGraphics#rotateZ(float) + * @see PGraphics#scale(float, float, float) + */ public void translate(float x, float y) { showMissingWarning("translate"); } @@ -5576,34 +5635,36 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Increases or decreases the size of a shape by expanding and contracting - * vertices. Objects always scale from their relative origin to the - * coordinate system. Scale values are specified as decimal percentages. - * For example, the function call scale(2.0) increases the dimension - * of a shape by 200%. Transformations apply to everything that happens - * after and subsequent calls to the function multiply the effect. For - * example, calling scale(2.0) and then scale(1.5) is the - * same as scale(3.0). If scale() is called within - * draw(), the transformation is reset when the loop begins again. - * Using this fuction with the z parameter requires using P3D as a - * parameter for size() as shown in the example above. This function - * can be further controlled by pushMatrix() and popMatrix(). - * - * - * @webref transform - * @webBrief Increases or decreases the size of a shape by expanding and contracting - * vertices. - * @param s percentage to scale the object - * @see PGraphics#pushMatrix() - * @see PGraphics#popMatrix() - * @see PGraphics#translate(float, float, float) - * @see PGraphics#rotate(float) - * @see PGraphics#rotateX(float) - * @see PGraphics#rotateY(float) - * @see PGraphics#rotateZ(float) - */ + /** + * + * Increases or decreases the size of a shape by expanding and contracting + * vertices. Objects always scale from their relative origin to the coordinate + * system. Scale values are specified as decimal percentages. For example, the + * function call scale(2.0) increases the dimension of a shape by + * 200%.
+ *
+ * Transformations apply to everything that happens after and subsequent calls + * to the function multiply the effect. For example, calling scale(2.0) + * and then scale(1.5) is the same as scale(3.0). If + * scale() is called within draw(), the transformation is reset + * when the loop begins again. Using this function with the z parameter + * requires using P3D as a parameter for size(), as shown in the third + * example above. This function can be further controlled with + * pushMatrix() and popMatrix(). + * + * + * @webref transform + * @webBrief Increases or decreases the size of a shape by expanding and + * contracting vertices. + * @param s percentage to scale the object + * @see PGraphics#pushMatrix() + * @see PGraphics#popMatrix() + * @see PGraphics#translate(float, float, float) + * @see PGraphics#rotate(float) + * @see PGraphics#rotateX(float) + * @see PGraphics#rotateY(float) + * @see PGraphics#rotateZ(float) + */ public void scale(float s) { showMissingWarning("scale"); } @@ -5705,19 +5766,19 @@ public class PGraphics extends PImage implements PConstants { // MATRIX FULL MONTY - /** - * - * Replaces the current matrix with the identity matrix. The equivalent - * function in OpenGL is glLoadIdentity(). - * - * - * @webref transform - * @webBrief Replaces the current matrix with the identity matrix. - * @see PGraphics#pushMatrix() - * @see PGraphics#popMatrix() - * @see PGraphics#applyMatrix(PMatrix) - * @see PGraphics#printMatrix() - */ + /** + * + * Replaces the current matrix with the identity matrix. The equivalent function + * in OpenGL is glLoadIdentity(). + * + * + * @webref transform + * @webBrief Replaces the current matrix with the identity matrix. + * @see PGraphics#pushMatrix() + * @see PGraphics#popMatrix() + * @see PGraphics#applyMatrix(PMatrix) + * @see PGraphics#printMatrix() + */ public void resetMatrix() { showMethodWarning("resetMatrix"); } @@ -5989,21 +6050,21 @@ public class PGraphics extends PImage implements PConstants { // PROJECTION - /** - * - * Sets an orthographic projection and defines a parallel clipping volume. - * All objects with the same dimension appear the same size, regardless of - * whether they are near or far from the camera. The parameters to this - * function specify the clipping volume where left and right are the - * minimum and maximum x values, top and bottom are the minimum and maximum - * y values, and near and far are the minimum and maximum z values. If no - * parameters are given, the default is used: ortho(0, width, 0, height, - * -10, 10). - * - * - * @webref lights_camera:camera - * @webBrief Sets an orthographic projection and defines a parallel clipping volume. - */ + /** + * + * Sets an orthographic projection and defines a parallel clipping volume. All + * objects with the same dimension appear the same size, regardless of whether + * they are near or far from the camera. The parameters to this function specify + * the clipping volume where left and right are the minimum and maximum x + * values, top and bottom are the minimum and maximum y values, and near and far + * are the minimum and maximum z values. If no parameters are given, the default + * is used: ortho(-width/2, width/2, -height/2, height/2). + * + * + * @webref lights_camera:camera + * @webBrief Sets an orthographic projection and defines a parallel clipping + * volume. + */ public void ortho() { showMissingWarning("ortho"); } @@ -6061,26 +6122,44 @@ public class PGraphics extends PImage implements PConstants { showMissingWarning("perspective"); } - /** - * - * Sets a perspective matrix defined through the parameters. Works like - * glFrustum, except it wipes out the current perspective matrix rather - * than muliplying itself with it. - * - * - * @webref lights_camera:camera - * @webBrief Sets a perspective matrix defined through the parameters. - * @param left left coordinate of the clipping plane - * @param right right coordinate of the clipping plane - * @param bottom bottom coordinate of the clipping plane - * @param top top coordinate of the clipping plane - * @param near near component of the clipping plane; must be greater than zero - * @param far far component of the clipping plane; must be greater than the near value - * @see PGraphics#camera(float, float, float, float, float, float, float, float, float) - * @see PGraphics#beginCamera() - * @see PGraphics#endCamera() - * @see PGraphics#perspective(float, float, float, float) - */ + /** + * + * Sets a perspective matrix as defined by the parameters.
+ *
+ * A frustum is a geometric form: a pyramid with its top cut off. With the + * viewer's eye at the imaginary top of the pyramid, the six planes of the + * frustum act as clipping planes when rendering a 3D view. Thus, any form + * inside the clipping planes is rendered and visible; anything outside those + * planes is not visible.
+ *
+ * Setting the frustum has the effect of changing the perspective with + * which the scene is rendered. This can be achieved more simply in many cases + * by using perspective().
+ *
+ * Note that the near value must be greater than zero (as the point of the + * frustum "pyramid" cannot converge "behind" the viewer). Similarly, the far + * value must be greater than the near value (as the "far" plane of the frustum + * must be "farther away" from the viewer than the near plane).
+ *
+ * Works like glFrustum, except it wipes out the current perspective matrix + * rather than multiplying itself with it. + * + * + * @webref lights_camera:camera + * @webBrief Sets a perspective matrix defined through the parameters. + * @param left left coordinate of the clipping plane + * @param right right coordinate of the clipping plane + * @param bottom bottom coordinate of the clipping plane + * @param top top coordinate of the clipping plane + * @param near near component of the clipping plane; must be greater than zero + * @param far far component of the clipping plane; must be greater than the + * near value + * @see PGraphics#camera(float, float, float, float, float, float, float, float, + * float) + * @see PGraphics#beginCamera() + * @see PGraphics#endCamera() + * @see PGraphics#perspective(float, float, float, float) + */ public void frustum(float left, float right, float bottom, float top, float near, float far) { @@ -6479,76 +6558,64 @@ public class PGraphics extends PImage implements PConstants { // STROKE CAP/JOIN/WEIGHT - /** - * - * Sets the width of the stroke used for lines, points, and the border - * around shapes. All widths are set in units of pixels. - *

- * When drawing with P3D, series of connected lines (such as the stroke - * around a polygon, triangle, or ellipse) produce unattractive results - * when a thick stroke weight is set (see - * Issue 123). With P3D, the minimum and maximum values for - * strokeWeight() are controlled by the graphics card and the - * operating system's OpenGL implementation. For instance, the thickness - * may not go higher than 10 pixels. - * - * - * @webref shape:attributes - * @webBrief Sets the width of the stroke used for lines, points, and the border - * around shapes. - * @param weight the weight (in pixels) of the stroke - * @see PGraphics#stroke(int, float) - * @see PGraphics#strokeJoin(int) - * @see PGraphics#strokeCap(int) - */ + /** + * + * Sets the width of the stroke used for lines, points, and the border around + * shapes. All widths are set in units of pixels.
+ *
+ * Using point() with strokeWeight(1) or smaller may draw nothing to the screen, + * depending on the graphics settings of the computer. Workarounds include + * setting the pixel using set() or drawing the point using either + * circle() or square(). + * + * + * @webref shape:attributes + * @webBrief Sets the width of the stroke used for lines, points, and the border + * around shapes. + * @param weight the weight (in pixels) of the stroke + * @see PGraphics#stroke(int, float) + * @see PGraphics#strokeJoin(int) + * @see PGraphics#strokeCap(int) + */ public void strokeWeight(float weight) { strokeWeight = weight; } - /** - * - * Sets the style of the joints which connect line segments. These joints - * are either mitered, beveled, or rounded and specified with the - * corresponding parameters MITER, BEVEL, and ROUND. The default joint is - * MITER. - *

- * This function is not available with the P3D renderer, (see - * Issue 123). More information about the renderers can be found in the - * size() reference. - * - * - * @webref shape:attributes - * @webBrief Sets the style of the joints which connect line segments. - * @param join either MITER, BEVEL, ROUND - * @see PGraphics#stroke(int, float) - * @see PGraphics#strokeWeight(float) - * @see PGraphics#strokeCap(int) - */ + /** + * + * Sets the style of the joints which connect line segments. These joints are + * either mitered, beveled, or rounded and specified with the corresponding + * parameters MITER, BEVEL, and ROUND. The default joint is MITER. + * + * + * @webref shape:attributes + * @webBrief Sets the style of the joints which connect line segments. + * @param join either MITER, BEVEL, ROUND + * @see PGraphics#stroke(int, float) + * @see PGraphics#strokeWeight(float) + * @see PGraphics#strokeCap(int) + */ public void strokeJoin(int join) { strokeJoin = join; } - /** - * - * Sets the style for rendering line endings. These ends are either - * squared, extended, or rounded and specified with the corresponding - * parameters SQUARE, PROJECT, and ROUND. The default cap is ROUND. - *

- * This function is not available with the P3D renderer (see - * Issue 123). More information about the renderers can be found in the - * size() reference. - * - * @webref shape:attributes - * @webBrief Sets the style for rendering line endings. - * @param cap either SQUARE, PROJECT, or ROUND - * @see PGraphics#stroke(int, float) - * @see PGraphics#strokeWeight(float) - * @see PGraphics#strokeJoin(int) - * @see PApplet#size(int, int, String, String) - */ + /** + * + * Sets the style for rendering line endings. These ends are either squared, + * extended, or rounded, each of which specified with the corresponding + * parameters: SQUARE, PROJECT, and ROUND. The default cap is ROUND.
+ *
+ * To make point() appear square, use strokeCap(PROJECT). Using + * strokeCap(SQUARE) (no cap) causes points to become invisible. + * + * @webref shape:attributes + * @webBrief Sets the style for rendering line endings. + * @param cap either SQUARE, PROJECT, or ROUND + * @see PGraphics#stroke(int, float) + * @see PGraphics#strokeWeight(float) + * @see PGraphics#strokeJoin(int) + * @see PApplet#size(int, int, String, String) + */ public void strokeCap(int cap) { strokeCap = cap; } @@ -6577,38 +6644,42 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the color used to draw lines and borders around shapes. This color - * is either specified in terms of the RGB or HSB color depending on the - * current colorMode() (the default color space is RGB, with each - * value in the range from 0 to 255). - *

- * When using hexadecimal notation to specify a color, use "#" or "0x" - * before the values (e.g. #CCFFAA, 0xFFCCFFAA). The # syntax uses six - * digits to specify a color (the way colors are specified in HTML and - * CSS). When using the hexadecimal notation starting with "0x", the - * hexadecimal value must be specified with eight characters; the first two - * characters define the alpha component and the remainder the red, green, - * and blue components. - *

- * The value for the parameter "gray" must be less than or equal to the - * current maximum value as specified by colorMode(). The default - * maximum value is 255. - * - * @webref color:setting - * @webBrief Sets the color used to draw lines and borders around shapes. - * @param rgb color value in hexadecimal notation - * @see PGraphics#noStroke() - * @see PGraphics#strokeWeight(float) - * @see PGraphics#strokeJoin(int) - * @see PGraphics#strokeCap(int) - * @see PGraphics#fill(int, float) - * @see PGraphics#noFill() - * @see PGraphics#tint(int, float) - * @see PGraphics#background(float, float, float, float) - * @see PGraphics#colorMode(int, float, float, float, float) - */ + /** + * + * Sets the color used to draw lines and borders around shapes. This color is + * either specified in terms of the RGB or HSB color depending on the current + * colorMode(). The default color space is RGB, with each value in the + * range from 0 to 255.
+ *
+ * When using hexadecimal notation to specify a color, use "#" or + * "0x" before the values (e.g., #CCFFAA or 0xFFCCFFAA). + * The # syntax uses six digits to specify a color (just as colors are + * typically specified in HTML and CSS). When using the hexadecimal notation + * starting with "0x", the hexadecimal value must be specified with eight + * characters; the first two characters define the alpha component, and the + * remainder define the red, green, and blue components.
+ *
+ * The value for the gray parameter must be less than or equal to the current + * maximum value as specified by colorMode(). The default maximum value + * is 255.
+ *
+ * When drawing in 2D with the default renderer, you may need + * hint(ENABLE_STROKE_PURE) to improve drawing quality (at the expense of + * performance). See the hint() documentation for more details. + * + * @webref color:setting + * @webBrief Sets the color used to draw lines and borders around shapes. + * @param rgb color value in hexadecimal notation + * @see PGraphics#noStroke() + * @see PGraphics#strokeWeight(float) + * @see PGraphics#strokeJoin(int) + * @see PGraphics#strokeCap(int) + * @see PGraphics#fill(int, float) + * @see PGraphics#noFill() + * @see PGraphics#tint(int, float) + * @see PGraphics#background(float, float, float, float) + * @see PGraphics#colorMode(int, float, float, float, float) + */ public void stroke(int rgb) { colorCalc(rgb); strokeFromCalc(); @@ -6695,39 +6766,39 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Sets the fill value for displaying images. Images can be tinted to - * specified colors or made transparent by setting the alpha.
- *
- * To make an image transparent, but not change it's color, use white as - * the tint color and specify an alpha value. For instance, tint(255, 128) - * will make an image 50% transparent (unless colorMode() has been - * used).
- *
- * When using hexadecimal notation to specify a color, use "#" or "0x" - * before the values (e.g. #CCFFAA, 0xFFCCFFAA). The # syntax uses six - * digits to specify a color (the way colors are specified in HTML and - * CSS). When using the hexadecimal notation starting with "0x", the - * hexadecimal value must be specified with eight characters; the first two - * characters define the alpha component and the remainder the red, green, - * and blue components.
- *
- * The value for the parameter "gray" must be less than or equal to the - * current maximum value as specified by colorMode(). The default - * maximum value is 255.
- *
- * The tint() function is also used to control the coloring of - * textures in 3D. - * - * - * @webref image:loading_displaying - * @webBrief Sets the fill value for displaying images. - * @usage web_application - * @param rgb color value in hexadecimal notation - * @see PGraphics#noTint() - * @see PGraphics#image(PImage, float, float, float, float) - */ + /** + * + * Sets the fill value for displaying images. Images can be tinted to specified + * colors or made transparent by including an alpha value.
+ *
+ * To apply transparency to an image without affecting its color, use white as + * the tint color and specify an alpha value. For instance, tint(255, + * 128) will make an image 50% transparent (assuming the default alpha range + * of 0-255, which can be changed with colorMode()).
+ *
+ * When using hexadecimal notation to specify a color, use "#" or + * "0x" before the values (e.g., #CCFFAA or 0xFFCCFFAA). + * The # syntax uses six digits to specify a color (just as colors are + * typically specified in HTML and CSS). When using the hexadecimal notation + * starting with "0x", the hexadecimal value must be specified with eight + * characters; the first two characters define the alpha component, and the + * remainder define the red, green, and blue components.
+ *
+ * The value for the gray parameter must be less than or equal to the current + * maximum value as specified by colorMode(). The default maximum value + * is 255.
+ *
+ * The tint() function is also used to control the coloring of textures + * in 3D. + * + * + * @webref image:loading_displaying + * @webBrief Sets the fill value for displaying images. + * @usage web_application + * @param rgb color value in hexadecimal notation + * @see PGraphics#noTint() + * @see PGraphics#image(PImage, float, float, float, float) + */ public void tint(int rgb) { colorCalc(rgb); tintFromCalc(); @@ -7162,29 +7233,30 @@ public class PGraphics extends PImage implements PConstants { showMethodWarning("noLights"); } - /** - * - * Adds an ambient light. Ambient light doesn't come from a specific - * direction, the rays have light have bounced around so much that objects - * are evenly lit from all sides. Ambient lights are almost always used in - * combination with other types of lights. Lights need to be included in - * the draw() to remain persistent in a looping program. Placing - * them in the setup() of a looping program will cause them to only - * have an effect the first time through the loop. The effect of the - * parameters is determined by the current color mode. - * - * - * @webref lights_camera:lights - * @webBrief Adds an ambient light. - * @usage web_application - * @param v1 red or hue value (depending on current color mode) - * @param v2 green or saturation value (depending on current color mode) - * @param v3 blue or brightness value (depending on current color mode) - * @see PGraphics#lights() - * @see PGraphics#directionalLight(float, float, float, float, float, float) - * @see PGraphics#pointLight(float, float, float, float, float, float) - * @see PGraphics#spotLight(float, float, float, float, float, float, float, float, float, float, float) - */ + /** + * + * Adds an ambient light. Ambient light doesn't come from a specific direction, + * the rays of light have bounced around so much that objects are evenly lit + * from all sides. Ambient lights are almost always used in combination with + * other types of lights. Lights need to be included in the draw() to + * remain persistent in a looping program. Placing them in the setup() of + * a looping program will cause them to only have an effect the first time + * through the loop. The v1, v2, and v3 parameters are + * interpreted as either RGB or HSB values, depending on the current color mode. + * + * + * @webref lights_camera:lights + * @webBrief Adds an ambient light. + * @usage web_application + * @param v1 red or hue value (depending on current color mode) + * @param v2 green or saturation value (depending on current color mode) + * @param v3 blue or brightness value (depending on current color mode) + * @see PGraphics#lights() + * @see PGraphics#directionalLight(float, float, float, float, float, float) + * @see PGraphics#pointLight(float, float, float, float, float, float) + * @see PGraphics#spotLight(float, float, float, float, float, float, float, + * float, float, float, float) + */ public void ambientLight(float v1, float v2, float v3) { showMethodWarning("ambientLight"); } @@ -7233,68 +7305,70 @@ public class PGraphics extends PImage implements PConstants { showMethodWarning("directionalLight"); } - /** - * - * Adds a point light. Lights need to be included in the draw() to - * remain persistent in a looping program. Placing them in the - * setup() of a looping program will cause them to only have an - * effect the first time through the loop. The affect of the v1, - * v2, and v3 parameters is determined by the current color - * mode. The x, y, and z parameters set the position - * of the light. - * - * - * @webref lights_camera:lights - * @webBrief Adds a point light. - * @usage web_application - * @param v1 red or hue value (depending on current color mode) - * @param v2 green or saturation value (depending on current color mode) - * @param v3 blue or brightness value (depending on current color mode) - * @param x x-coordinate of the light - * @param y y-coordinate of the light - * @param z z-coordinate of the light - * @see PGraphics#lights() - * @see PGraphics#directionalLight(float, float, float, float, float, float) - * @see PGraphics#ambientLight(float, float, float, float, float, float) - * @see PGraphics#spotLight(float, float, float, float, float, float, float, float, float, float, float) - */ + /** + * + * Adds a point light. Lights need to be included in the draw() to remain + * persistent in a looping program. Placing them in the setup() of a + * looping program will cause them to only have an effect the first time through + * the loop. The v1, v2, and v3 parameters are interpreted + * as either RGB or HSB values, depending on the current color mode. The + * x, y, and z parameters set the position of the light. + * + * + * @webref lights_camera:lights + * @webBrief Adds a point light. + * @usage web_application + * @param v1 red or hue value (depending on current color mode) + * @param v2 green or saturation value (depending on current color mode) + * @param v3 blue or brightness value (depending on current color mode) + * @param x x-coordinate of the light + * @param y y-coordinate of the light + * @param z z-coordinate of the light + * @see PGraphics#lights() + * @see PGraphics#directionalLight(float, float, float, float, float, float) + * @see PGraphics#ambientLight(float, float, float, float, float, float) + * @see PGraphics#spotLight(float, float, float, float, float, float, float, + * float, float, float, float) + */ public void pointLight(float v1, float v2, float v3, float x, float y, float z) { showMethodWarning("pointLight"); } - /** - * - * Adds a spot light. Lights need to be included in the draw() to - * remain persistent in a looping program. Placing them in the - * setup() of a looping program will cause them to only have an - * effect the first time through the loop. The affect of the v1, - * v2, and v3 parameters is determined by the current color - * mode. The x, y, and z parameters specify the - * position of the light and nx, ny, nz specify the - * direction or light. The angle parameter affects angle of the - * spotlight cone. - * - * - * @webref lights_camera:lights - * @webBrief Adds a spot light. - * @usage web_application - * @param v1 red or hue value (depending on current color mode) - * @param v2 green or saturation value (depending on current color mode) - * @param v3 blue or brightness value (depending on current color mode) - * @param x x-coordinate of the light - * @param y y-coordinate of the light - * @param z z-coordinate of the light - * @param nx direction along the x axis - * @param ny direction along the y axis - * @param nz direction along the z axis - * @param angle angle of the spotlight cone - * @param concentration exponent determining the center bias of the cone - * @see PGraphics#lights() - * @see PGraphics#directionalLight(float, float, float, float, float, float) - * @see PGraphics#pointLight(float, float, float, float, float, float) - * @see PGraphics#ambientLight(float, float, float, float, float, float) - */ + /** + * + * Adds a spot light. Lights need to be included in the draw() to remain + * persistent in a looping program. Placing them in the setup() of a + * looping program will cause them to only have an effect the first time through + * the loop. The v1, v2, and v3 parameters are interpreted + * as either RGB or HSB values, depending on the current color mode. The + * x, y, and z parameters specify the position of the light + * and nx, ny, nz specify the direction of light. The + * angle parameter affects angle of the spotlight cone, while + * concentration sets the bias of light focusing toward the center of + * that cone. + * + * @webref lights_camera:lights + * @webBrief Adds a spot light. + * @usage web_application + * @param v1 red or hue value (depending on current color mode) + * @param v2 green or saturation value (depending on current color + * mode) + * @param v3 blue or brightness value (depending on current color + * mode) + * @param x x-coordinate of the light + * @param y y-coordinate of the light + * @param z z-coordinate of the light + * @param nx direction along the x axis + * @param ny direction along the y axis + * @param nz direction along the z axis + * @param angle angle of the spotlight cone + * @param concentration exponent determining the center bias of the cone + * @see PGraphics#lights() + * @see PGraphics#directionalLight(float, float, float, float, float, float) + * @see PGraphics#pointLight(float, float, float, float, float, float) + * @see PGraphics#ambientLight(float, float, float, float, float, float) + */ public void spotLight(float v1, float v2, float v3, float x, float y, float z, float nx, float ny, float nz, @@ -7302,35 +7376,38 @@ public class PGraphics extends PImage implements PConstants { showMethodWarning("spotLight"); } - /** - * - * Sets the falloff rates for point lights, spot lights, and ambient - * lights. The parameters are used to determine the falloff with the - * following equation:

d = distance from light position to - * vertex position
falloff = 1 / (CONSTANT + d * LINEAR + (d*d) * - * QUADRATIC)

Like fill(), it affects only the elements - * which are created after it in the code. The default value if - * LightFalloff(1.0, 0.0, 0.0). Thinking about an ambient light with - * a falloff can be tricky. It is used, for example, if you wanted a region - * of your scene to be lit ambiently one color and another region to be lit - * ambiently by another color, you would use an ambient light with location - * and falloff. You can think of it as a point light that doesn't care - * which direction a surface is facing. - * - * - * @webref lights_camera:lights - * @webBrief Sets the falloff rates for point lights, spot lights, and ambient - * lights. - * @usage web_application - * @param constant constant value or determining falloff - * @param linear linear value for determining falloff - * @param quadratic quadratic value for determining falloff - * @see PGraphics#lights() - * @see PGraphics#ambientLight(float, float, float, float, float, float) - * @see PGraphics#pointLight(float, float, float, float, float, float) - * @see PGraphics#spotLight(float, float, float, float, float, float, float, float, float, float, float) - * @see PGraphics#lightSpecular(float, float, float) - */ + /** + * + * Sets the falloff rates for point lights, spot lights, and ambient lights. + * Like fill(), it affects only the elements which are created after it + * in the code. The default value is lightFalloff(1.0, 0.0, 0.0), and the + * parameters are used to calculate the falloff with the following + * equation:
+ *
+ * d = distance from light position to vertex position
+ * falloff = 1 / (CONSTANT + d * LINEAR + (d*d) * QUADRATIC)
+ *
+ * Thinking about an ambient light with a falloff can be tricky. If you want a + * region of your scene to be lit ambiently with one color and another region to + * be lit ambiently with another color, you could use an ambient light with + * location and falloff. You can think of it as a point light that doesn't care + * which direction a surface is facing. + * + * + * @webref lights_camera:lights + * @webBrief Sets the falloff rates for point lights, spot lights, and ambient + * lights. + * @usage web_application + * @param constant constant value or determining falloff + * @param linear linear value for determining falloff + * @param quadratic quadratic value for determining falloff + * @see PGraphics#lights() + * @see PGraphics#ambientLight(float, float, float, float, float, float) + * @see PGraphics#pointLight(float, float, float, float, float, float) + * @see PGraphics#spotLight(float, float, float, float, float, float, float, + * float, float, float, float) + * @see PGraphics#lightSpecular(float, float, float) + */ public void lightFalloff(float constant, float linear, float quadratic) { showMethodWarning("lightFalloff"); } @@ -7369,42 +7446,49 @@ public class PGraphics extends PImage implements PConstants { // BACKGROUND - /** - * - * The background() function sets the color used for the background - * of the Processing window. The default background is light gray. In the - * draw() function, the background color is used to clear the - * display window at the beginning of each frame. - *

- * An image can also be used as the background for a sketch, however its - * width and height must be the same size as the sketch window. To resize - * an image 'b' to the size of the sketch window, use b.resize(width, height). - *

- * Images used as background will ignore the current tint() setting. - *

- * It is not possible to use transparency (alpha) in background colors with - * the main drawing surface, however they will work properly with createGraphics(). - * - * - *

Advanced

- *

Clear the background with a color that includes an alpha value. This can - * only be used with objects created by createGraphics(), because the main - * drawing surface cannot be set transparent.

- *

It might be tempting to use this function to partially clear the screen - * on each frame, however that's not how this function works. When calling - * background(), the pixels will be replaced with pixels that have that level - * of transparency. To do a semi-transparent overlay, use fill() with alpha - * and draw a rectangle.

- * - * @webref color:setting - * @webBrief Sets the color used for the background of the Processing window. - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#stroke(float) - * @see PGraphics#fill(float) - * @see PGraphics#tint(float) - * @see PGraphics#colorMode(int) - */ + /** + * + * The background() function sets the color used for the background of + * the Processing window. The default background is light gray. This function is + * typically used within draw() to clear the display window at the + * beginning of each frame, but it can be used inside setup() to set the + * background on the first frame of animation or if the backgound need only be + * set once.
+ *
+ * An image can also be used as the background for a sketch, although the + * image's width and height must match that of the sketch window. Images used + * with background() will ignore the current tint() setting. To + * resize an image to the size of the sketch window, use image.resize(width, + * height).
+ *
+ * It is not possible to use the transparency alpha parameter with + * background colors on the main drawing surface. It can only be used along with + * a PGraphics object and createGraphics(). + * + * + *

Advanced

+ *

+ * Clear the background with a color that includes an alpha value. This can only + * be used with objects created by createGraphics(), because the main drawing + * surface cannot be set transparent. + *

+ *

+ * It might be tempting to use this function to partially clear the screen on + * each frame, however that's not how this function works. When calling + * background(), the pixels will be replaced with pixels that have that level of + * transparency. To do a semi-transparent overlay, use fill() with alpha and + * draw a rectangle. + *

+ * + * @webref color:setting + * @webBrief Sets the color used for the background of the Processing window. + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#stroke(float) + * @see PGraphics#fill(float) + * @see PGraphics#tint(float) + * @see PGraphics#colorMode(int) + */ public void background(int rgb) { // if (((rgb & 0xff000000) == 0) && (rgb <= colorModeX)) { // background((float) rgb); @@ -7491,6 +7575,7 @@ public class PGraphics extends PImage implements PConstants { * can be entirely or partially transparent. This function clears * everything in a PGraphics object to make all of the pixels * 100% transparent. + * * @webref color:setting * @webBrief Clears the pixels within a buffer. */ @@ -7601,26 +7686,36 @@ public class PGraphics extends PImage implements PConstants { // COLOR MODE - /** - * - * Changes the way Processing interprets color data. By default, the - * parameters for fill(), stroke(), background(), and - * color() are defined by values between 0 and 255 using the RGB - * color model. The colorMode() function is used to change the - * numerical range used for specifying colors and to switch color systems. - * For example, calling colorMode(RGB, 1.0) will specify that values - * are specified between 0 and 1. The limits for defining colors are - * altered by setting the parameters range1, range2, range3, and range 4. - * - * - * @webref color:setting - * @webBrief Changes the way Processing interprets color data. - * @usage web_application - * @param mode Either RGB or HSB, corresponding to Red/Green/Blue and Hue/Saturation/Brightness - * @see PGraphics#background(float) - * @see PGraphics#fill(float) - * @see PGraphics#stroke(float) - */ + /** + * + * Changes the way Processing interprets color data. By default, the parameters + * for fill(), stroke(), background(), and color() + * are defined by values between 0 and 255 using the RGB color model. The + * colorMode() function is used to change the numerical range used for + * specifying colors and to switch color systems. For example, calling + * colorMode(RGB, 1.0) will specify that values are specified between 0 + * and 1. The limits for defining colors are altered by setting the parameters + * max, max1, max2, max3, and maxA.
+ *
+ * After changing the range of values for colors with code like + * colorMode(HSB, 360, 100, 100), those ranges remain in use until they + * are explicitly changed again. For example, after running colorMode(HSB, + * 360, 100, 100) and then changing back to colorMode(RGB), the range + * for R will be 0 to 360 and the range for G and B will be 0 to 100. To avoid + * this, be explicit about the ranges when changing the color mode. For + * instance, instead of colorMode(RGB), write colorMode(RGB, 255, 255, + * 255). + * + * + * @webref color:setting + * @webBrief Changes the way Processing interprets color data. + * @usage web_application + * @param mode Either RGB or HSB, corresponding to Red/Green/Blue and + * Hue/Saturation/Brightness + * @see PGraphics#background(float) + * @see PGraphics#fill(float) + * @see PGraphics#stroke(float) + */ public void colorMode(int mode) { colorMode(mode, colorModeX, colorModeY, colorModeZ, colorModeA); } @@ -7967,31 +8062,39 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Extracts the red value from a color, scaled to match current - * colorMode(). This value is always returned as a float so be - * careful not to assign it to an int value.

The red() function - * is easy to use and undestand, but is slower than another technique. To - * achieve the same results when working in colorMode(RGB, 255), but - * with greater speed, use the >> (right shift) operator with a bit - * mask. For example, the following two lines of code are equivalent:
float r1 = red(myColor);
float r2 = myColor >> 16
-   * & 0xFF;
- * - * - * @webref color:creating_reading - * @webBrief Extracts the red value from a color, scaled to match current colorMode(). - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#green(int) - * @see PGraphics#blue(int) - * @see PGraphics#alpha(int) - * @see PGraphics#hue(int) - * @see PGraphics#saturation(int) - * @see PGraphics#brightness(int) - * @see_external rightshift - */ + /** + * + * Extracts the red value from a color, scaled to match current + * colorMode(). The value is always returned as a float, so be careful + * not to assign it to an int value.
+ *
+ * The red() function is easy to use and understand, but it is slower + * than a technique called bit shifting. When working in colorMode(RGB, + * 255), you can acheive the same results as red() but with greater + * speed by using the right shift operator (>>) with a bit mask. For + * example, the following two lines of code are equivalent means of getting the + * red value of the color value c:
+ *
+ * + * 
+	 * float r1 = red(c); // Simpler, but slower to calculate
+	 * float r2 = c >> 16 & 0xFF; // Very fast to calculate
+	 *
+ * + * + * @webref color:creating_reading + * @webBrief Extracts the red value from a color, scaled to match current + * colorMode(). + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#green(int) + * @see PGraphics#blue(int) + * @see PGraphics#alpha(int) + * @see PGraphics#hue(int) + * @see PGraphics#saturation(int) + * @see PGraphics#brightness(int) + * @see_external rightshift + */ public final float red(int rgb) { float c = (rgb >> 16) & 0xff; if (colorModeDefault) return c; @@ -7999,31 +8102,39 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Extracts the green value from a color, scaled to match current - * colorMode(). This value is always returned as a float so be - * careful not to assign it to an int value.

The green() - * function is easy to use and undestand, but is slower than another - * technique. To achieve the same results when working in colorMode(RGB, - * 255), but with greater speed, use the >> (right shift) - * operator with a bit mask. For example, the following two lines of code - * are equivalent:
float r1 = green(myColor);
float r2 =
-   * myColor >> 8 & 0xFF;
- * - * - * @webref color:creating_reading - * @webBrief Extracts the green value from a color, scaled to match current colorMode(). - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#red(int) - * @see PGraphics#blue(int) - * @see PGraphics#alpha(int) - * @see PGraphics#hue(int) - * @see PGraphics#saturation(int) - * @see PGraphics#brightness(int) - * @see_external rightshift - */ + /** + * + * Extracts the green value from a color, scaled to match current + * colorMode(). The value is always returned as a float, so be careful + * not to assign it to an int value.
+ *
+ * The green() function is easy to use and understand, but it is slower + * than a technique called bit shifting. When working in colorMode(RGB, + * 255), you can acheive the same results as green() but with greater + * speed by using the right shift operator (>>) with a bit mask. For + * example, the following two lines of code are equivalent means of getting the + * green value of the color value c:
+ *
+ * + * 
+	 * float g1 = green(c); // Simpler, but slower to calculate
+	 * float g2 = c >> 8 & 0xFF; // Very fast to calculate
+	 *
+ * + * + * @webref color:creating_reading + * @webBrief Extracts the green value from a color, scaled to match current + * colorMode(). + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#red(int) + * @see PGraphics#blue(int) + * @see PGraphics#alpha(int) + * @see PGraphics#hue(int) + * @see PGraphics#saturation(int) + * @see PGraphics#brightness(int) + * @see_external rightshift + */ public final float green(int rgb) { float c = (rgb >> 8) & 0xff; if (colorModeDefault) return c; @@ -8031,31 +8142,39 @@ public class PGraphics extends PImage implements PConstants { } - /** - * - * Extracts the blue value from a color, scaled to match current - * colorMode(). This value is always returned as a float so be - * careful not to assign it to an int value.

The blue() - * function is easy to use and undestand, but is slower than another - * technique. To achieve the same results when working in colorMode(RGB, - * 255), but with greater speed, use a bit mask to remove the other - * color components. For example, the following two lines of code are - * equivalent:
float r1 = blue(myColor);
float r2 = myColor
-   * & 0xFF;
- * - * - * @webref color:creating_reading - * @webBrief Extracts the blue value from a color, scaled to match current colorMode(). - * @usage web_application - * @param rgb any value of the color datatype - * @see PGraphics#red(int) - * @see PGraphics#green(int) - * @see PGraphics#alpha(int) - * @see PGraphics#hue(int) - * @see PGraphics#saturation(int) - * @see PGraphics#brightness(int) - * @see_external rightshift - */ + /** + * + * Extracts the blue value from a color, scaled to match current + * colorMode(). The value is always returned as a float, so be careful + * not to assign it to an int value.
+ *
+ * The blue() function is easy to use and understand, but it is slower + * than a technique called bit masking. When working in colorMode(RGB, + * 255), you can acheive the same results as blue() but with greater + * speed by using a bit mask to remove the other color components. For example, + * the following two lines of code are equivalent means of getting the blue + * value of the color value c:
+ *
+ * + * 
+	 * float b1 = blue(c); // Simpler, but slower to calculate
+	 * float b2 = c & 0xFF; // Very fast to calculate
+	 *
+ * + * + * @webref color:creating_reading + * @webBrief Extracts the blue value from a color, scaled to match current + * colorMode(). + * @usage web_application + * @param rgb any value of the color datatype + * @see PGraphics#red(int) + * @see PGraphics#green(int) + * @see PGraphics#alpha(int) + * @see PGraphics#hue(int) + * @see PGraphics#saturation(int) + * @see PGraphics#brightness(int) + * @see_external rightshift + */ public final float blue(int rgb) { float c = (rgb) & 0xff; if (colorModeDefault) return c; @@ -8147,24 +8266,29 @@ public class PGraphics extends PImage implements PConstants { // Against our better judgement. - /** - * - * Calculates a color or colors between two color at a specific increment. - * The amt parameter is the amount to interpolate between the two - * values where 0.0 equal to the first point, 0.1 is very near the first - * point, 0.5 is half-way in between, etc. - * - * - * @webref color:creating_reading - * @webBrief Calculates a color or colors between two color at a specific increment. - * @usage web_application - * @param c1 interpolate from this color - * @param c2 interpolate to this color - * @param amt between 0.0 and 1.0 - * @see PImage#blendColor(int, int, int) - * @see PGraphics#color(float, float, float, float) - * @see PApplet#lerp(float, float, float) - */ + /** + * + * Calculates a color between two colors at a specific increment. The amt + * parameter is the amount to interpolate between the two values where 0.0 is + * equal to the first point, 0.1 is very near the first point, 0.5 is halfway in + * between, etc.
+ * An amount below 0 will be treated as 0. Likewise, amounts above 1 will be + * capped at 1. This is different from the behavior of lerp(), but necessary + * because otherwise numbers outside the range will produce strange and + * unexpected colors. + * + * + * @webref color:creating_reading + * @webBrief Calculates a color or colors between two color at a specific + * increment. + * @usage web_application + * @param c1 interpolate from this color + * @param c2 interpolate to this color + * @param amt between 0.0 and 1.0 + * @see PImage#blendColor(int, int, int) + * @see PGraphics#color(float, float, float, float) + * @see PApplet#lerp(float, float, float) + */ public int lerpColor(int c1, int c2, float amt) { // ignore return lerpColor(c1, c2, amt, colorMode); } diff --git a/core/src/processing/core/PImage.java b/core/src/processing/core/PImage.java index 05668d401..bc84d44cd 100644 --- a/core/src/processing/core/PImage.java +++ b/core/src/processing/core/PImage.java @@ -35,22 +35,24 @@ import processing.awt.ShimAWT; /** - * - * Datatype for storing images. Processing can display .gif, - * .jpg, .tga, and .png images. Images may be - * displayed in 2D and 3D space. Before an image is used, it must be loaded - * with the loadImage() function. The PImage class contains - * fields for the width and height of the image, as well as - * an array called pixels[] that contains the values for every pixel - * in the image. The methods described below allow easy access to the - * image's pixels and alpha channel and simplify the process of compositing.
- *
using the pixels[] array, be sure to use the - * loadPixels() method on the image to make sure that the pixel data - * is properly loaded.
- *
create a new image, use the createImage() function. Do not - * use the syntax new PImage(). - * - * + * + * Datatype for storing images. Processing can display .gif, .jpg, + * .tga, and .png images. Images may be displayed in 2D and 3D + * space. Before an image is used, it must be loaded with the loadImage() + * function. The PImage class contains fields for the width and + * height of the image, as well as an array called pixels[] that + * contains the values for every pixel in the image. The methods described below + * allow easy access to the image's pixels and alpha channel and simplify the + * process of compositing.
+ *
+ * Before using the pixels[] array, be sure to use the + * loadPixels() method on the image to make sure that the pixel data is + * properly loaded.
+ *
+ * To create a new image, use the createImage() function. Do not use the + * syntax new PImage(). + * + * * @webref image * @webBrief Datatype for storing images. * @usage Web & Application @@ -79,28 +81,24 @@ public class PImage implements PConstants, Cloneable { */ public int format; - /** - * - * Array containing the values for all the pixels in the display window. - * These values are of the color datatype. This array is the size of the - * display window. For example, if the image is 100x100 pixels, there will - * be 10000 values and if the window is 200x300 pixels, there will be 60000 - * values. The index value defines the position of a value within - * the array. For example, the statement color b = pixels[230] will - * set the variable b to be equal to the value at that location in - * the array.
- *
- * Before accessing this array, the data must loaded with the - * loadPixels() function. After the array data has been modified, - * the updatePixels() function must be run to update the changes. - * Without loadPixels(), running the code may (or will in future - * releases) result in a NullPointerException. - * - * - * @webref image:pixels - * @webBrief Array containing the color of every pixel in the image. - * @usage web_application - */ + /** + * + * The pixels[] array contains the values for all the pixels in the image. These + * values are of the color datatype. This array is the size of the image, + * meaning if the image is 100 x 100 pixels, there will be 10,000 values and if + * the window is 200 x 300 pixels, there will be 60,000 values.
+ *
+ * Before accessing this array, the data must loaded with the + * loadPixels() method. Failure to do so may result in a + * NullPointerException. After the array data has been modified, the + * updatePixels() method must be run to update the content of the display + * window. + * + * + * @webref image:pixels + * @webBrief Array containing the color of every pixel in the image. + * @usage web_application + */ public int[] pixels; /** 1 for most images, 2 for hi-dpi/retina */ @@ -375,29 +373,23 @@ public class PImage implements PConstants, Cloneable { } - /** - * - * Loads the pixel data for the image into its pixels[] array. This - * function must always be called before reading from or writing to pixels[]. - *

renderers may or may not seem to require loadPixels() - * or updatePixels(). However, the rule is that any time you want to - * manipulate the pixels[] array, you must first call - * loadPixels(), and after changes have been made, call - * updatePixels(). Even if the renderer may not seem to use this - * function in the current Processing release, this will always be subject - * to change. - * - * - *

Advanced

- * Call this when you want to mess with the pixels[] array. - *

- * For subclasses where the pixels[] buffer isn't set by default, - * this should copy all data into the pixels[] array - * - * @webref pimage:pixels - * @webBrief Loads the pixel data for the image into its pixels[] array. - * @usage web_application - */ + /** + * + * Loads the pixel data of the current display window into the pixels[] + * array. This function must always be called before reading from or writing to + * pixels[]. Subsequent changes to the display window will not be + * reflected in pixels until loadPixels() is called again. + * + * + *

Advanced

Call this when you want to mess with the pixels[] array. + *

+ * For subclasses where the pixels[] buffer isn't set by default, this should + * copy all data into the pixels[] array + * + * @webref pimage:pixels + * @webBrief Loads the pixel data for the image into its pixels[] array. + * @usage web_application + */ public void loadPixels() { // ignore if (pixels == null || pixels.length != pixelWidth*pixelHeight) { pixels = new int[pixelWidth*pixelHeight]; @@ -411,35 +403,26 @@ public class PImage implements PConstants, Cloneable { } - /** - * - * Updates the image with the data in its pixels[] array. Use in - * conjunction with loadPixels(). If you're only reading pixels from - * the array, there's no need to call updatePixels(). - *

renderers may or may not seem to require loadPixels() - * or updatePixels(). However, the rule is that any time you want to - * manipulate the pixels[] array, you must first call - * loadPixels(), and after changes have been made, call - * updatePixels(). Even if the renderer may not seem to use this - * function in the current Processing release, this will always be subject - * to change. - *

- * Currently, none of the renderers use the additional parameters to - * updatePixels(), however this may be implemented in the future. - * - *

Advanced

- * Mark the pixels in this region as needing an update. - * This is not currently used by any of the renderers, however the api - * is structured this way in the hope of being able to use this to - * speed things up in the future. - * @webref pimage:pixels - * @webBrief Updates the image with the data in its pixels[] array. - * @usage web_application - * @param x x-coordinate of the upper-left corner - * @param y y-coordinate of the upper-left corner - * @param w width - * @param h height - */ + /** + * + * Updates the display window with the data in the pixels[] array. Use in + * conjunction with loadPixels(). If you're only reading pixels from the + * array, there's no need to call updatePixels() — updating is only + * necessary to apply changes. + * + *

Advanced

Mark the pixels in this region as needing an update. This + * is not currently used by any of the renderers, however the api is structured + * this way in the hope of being able to use this to speed things up in the + * future. + * + * @webref pimage:pixels + * @webBrief Updates the image with the data in its pixels[] array. + * @usage web_application + * @param x x-coordinate of the upper-left corner + * @param y y-coordinate of the upper-left corner + * @param w width + * @param h height + */ public void updatePixels(int x, int y, int w, int h) { // ignore int x2 = x + w; int y2 = y + h; @@ -928,57 +911,67 @@ public class PImage implements PConstants, Cloneable { } - /** - * - * Filters an image as defined by one of the following modes:

THRESHOLD - converts the image to black and white pixels depending if - * they are above or below the threshold defined by the level parameter. - * The level must be between 0.0 (black) and 1.0(white). If no level is - * specified, 0.5 is used.
- *
- * GRAY - converts any colors in the image to grayscale equivalents
- *
- * INVERT - sets each pixel to its inverse value
- *
- * POSTERIZE - limits each channel of the image to the number of colors - * specified as the level parameter
- *
- * BLUR - executes a Guassian blur with the level parameter specifying the - * extent of the blurring. If no level parameter is used, the blur is - * equivalent to Guassian blur of radius 1
- *
- * OPAQUE - sets the alpha channel to entirely opaque
- *
- * ERODE - reduces the light areas with the amount defined by the level - * parameter
- *
- * DILATE - increases the light areas with the amount defined by the level parameter - * - * - *

Advanced

- * Method to apply a variety of basic filters to this image. - *

- *

    - *
  • filter(BLUR) provides a basic blur. - *
  • filter(GRAY) converts the image to grayscale based on luminance. - *
  • filter(INVERT) will invert the color components in the image. - *
  • filter(OPAQUE) set all the high bits in the image to opaque - *
  • filter(THRESHOLD) converts the image to black and white. - *
  • filter(DILATE) grow white/light areas - *
  • filter(ERODE) shrink white/light areas - *
- * Luminance conversion code contributed by - * toxi - *

- * Gaussian blur code contributed by - * Mario Klingemann - * - * @webref image:pixels - * @webBrief Converts the image to grayscale or black and white - * @usage web_application - * @param kind Either THRESHOLD, GRAY, OPAQUE, INVERT, POSTERIZE, BLUR, ERODE, or DILATE - * @param param unique for each, see above - */ + /** + * + * Filters the image as defined by one of the following modes:
+ *
+ * THRESHOLD
+ * Converts the image to black and white pixels depending if they are above or + * below the threshold defined by the level parameter. The parameter must be + * between 0.0 (black) and 1.0 (white). If no level is specified, 0.5 is + * used.
+ *
+ * GRAY
+ * Converts any colors in the image to grayscale equivalents. No parameter is + * used.
+ *
+ * OPAQUE
+ * Sets the alpha channel to entirely opaque. No parameter is used.
+ *
+ * INVERT
+ * Sets each pixel to its inverse value. No parameter is used.
+ *
+ * POSTERIZE
+ * Limits each channel of the image to the number of colors specified as the + * parameter. The parameter can be set to values between 2 and 255, but results + * are most noticeable in the lower ranges.
+ *
+ * BLUR
+ * Executes a Gaussian blur with the level parameter specifying the extent of + * the blurring. If no parameter is used, the blur is equivalent to Gaussian + * blur of radius 1. Larger values increase the blur.
+ *
+ * ERODE
+ * Reduces the light areas. No parameter is used.
+ *
+ * DILATE
+ * Increases the light areas. No parameter is used. + * + * + *

Advanced

Method to apply a variety of basic filters to this image. + *

+ *

    + *
  • filter(BLUR) provides a basic blur. + *
  • filter(GRAY) converts the image to grayscale based on luminance. + *
  • filter(INVERT) will invert the color components in the image. + *
  • filter(OPAQUE) set all the high bits in the image to opaque + *
  • filter(THRESHOLD) converts the image to black and white. + *
  • filter(DILATE) grow white/light areas + *
  • filter(ERODE) shrink white/light areas + *
+ * Luminance conversion code contributed by + * toxi + *

+ * Gaussian blur code contributed by + * Mario Klingemann + * + * @webref image:pixels + * @webBrief Converts the image to grayscale or black and white + * @usage web_application + * @param kind Either THRESHOLD, GRAY, OPAQUE, INVERT, POSTERIZE, BLUR, ERODE, + * or DILATE + * @param param unique for each, see above + */ public void filter(int kind, float param) { loadPixels(); diff --git a/core/src/processing/core/PShape.java b/core/src/processing/core/PShape.java index 953161dc7..568f9a863 100644 --- a/core/src/processing/core/PShape.java +++ b/core/src/processing/core/PShape.java @@ -37,43 +37,54 @@ import java.util.Base64; /** * - * Datatype for storing shapes. Processing can currently load and display - * SVG (Scalable Vector Graphics) shapes. Before a shape is used, it must - * be loaded with the loadShape() function. The shape() - * function is used to draw the shape to the display window. The - * PShape object contain a group of methods, linked below, that can - * operate on the shape data. - *

- * The loadShape() function supports SVG files created with Inkscape - * and Adobe Illustrator. It is not a full SVG implementation, but offers - * some straightforward support for handling vector data. + * Datatype for storing shapes. Before a shape is used, it must be loaded with + * the loadShape() or created with the createShape(). The + * shape() function is used to draw the shape to the display window. + * Processing can currently load and display SVG (Scalable Vector Graphics) and + * OBJ shapes. OBJ files can only be opened using the P3D renderer. The + * loadShape() function supports SVG files created with Inkscape and + * Adobe Illustrator. It is not a full SVG implementation, but offers some + * straightforward support for handling vector data.
+ *
+ * The PShape object contains a group of methods that can operate on the + * shape data. Some of the methods are listed below, but the full list used for + * creating and modifying shapes is + * available + * here in the Processing Javadoc.
+ *
+ * To create a new shape, use the createShape() function. Do not use the + * syntax new PShape(). * *

Advanced

* - * In-progress class to handle shape data, currently to be considered of - * alpha or beta quality. Major structural work may be performed on this class - * after the release of Processing 1.0. Such changes may include: + * In-progress class to handle shape data, currently to be considered of alpha + * or beta quality. Major structural work may be performed on this class after + * the release of Processing 1.0. Such changes may include: * *
    - *
  • addition of proper accessors to read shape vertex and coloring data - * (this is the second most important part of having a PShape class after all). - *
  • a means of creating PShape objects ala beginShape() and endShape(). - *
  • load(), update(), and cache methods ala PImage, so that shapes can - * have renderer-specific optimizations, such as vertex arrays in OpenGL. - *
  • splitting this class into multiple classes to handle different - * varieties of shape data (primitives vs collections of vertices vs paths) - *
  • change of package declaration, for instance moving the code into - * package processing.shape (if the code grows too much). + *
  • addition of proper accessors to read shape vertex and coloring data (this + * is the second most important part of having a PShape class after all). + *
  • a means of creating PShape objects ala beginShape() and endShape(). + *
  • load(), update(), and cache methods ala PImage, so that shapes can have + * renderer-specific optimizations, such as vertex arrays in OpenGL. + *
  • splitting this class into multiple classes to handle different varieties + * of shape data (primitives vs collections of vertices vs paths) + *
  • change of package declaration, for instance moving the code into package + * processing.shape (if the code grows too much). *
* - *

For the time being, this class and its shape() and loadShape() friends in - * PApplet exist as placeholders for more exciting things to come. If you'd - * like to work with this class, make a subclass (see how PShapeSVG works) - * and you can play with its internal methods all you like.

+ *

+ * For the time being, this class and its shape() and loadShape() friends in + * PApplet exist as placeholders for more exciting things to come. If you'd like + * to work with this class, make a subclass (see how PShapeSVG works) and you + * can play with its internal methods all you like. + *

* - *

Library developers are encouraged to create PShape objects when loading - * shape data, so that they can eventually hook into the bounty that will be - * the PShape interface, and the ease of loadShape() and shape().

+ *

+ * Library developers are encouraged to create PShape objects when loading shape + * data, so that they can eventually hook into the bounty that will be the + * PShape interface, and the ease of loadShape() and shape(). + *

* * @webref shape * @webBrief Datatype for storing shapes. @@ -387,40 +398,41 @@ public class PShape implements PConstants { return name; } - /** - * - * Returns a boolean value "true" if the image is set to be visible, - * "false" if not. This is modified with the setVisible() parameter. - *

- * The visibility of a shape is usually controlled by whatever program - * created the SVG file. For instance, this parameter is controlled by - * showing or hiding the shape in the layers palette in Adobe Illustrator. - * - * @webref pshape:method - * @usage web_application - * @webBrief Returns a boolean value "true" if the image is set to be visible, "false" if not - * @see PShape#setVisible(boolean) - */ + /** + * + * Returns a boolean value "true" if the image is set to be visible, "false" if + * not. This value can be modified with the setVisible() method.
+ *
+ * The default visibility of a shape is usually controlled by whatever program + * created the SVG file. For instance, this parameter is controlled by showing + * or hiding the shape in the layers palette in Adobe Illustrator. + * + * @webref pshape:method + * @usage web_application + * @webBrief Returns a boolean value "true" if the image is set to be visible, + * "false" if not + * @see PShape#setVisible(boolean) + */ public boolean isVisible() { return visible; } - /** - * - * Sets the shape to be visible or invisible. This is determined by the - * value of the visible parameter. - *

- * The visibility of a shape is usually controlled by whatever program - * created the SVG file. For instance, this parameter is controlled by - * showing or hiding the shape in the layers palette in Adobe Illustrator. - * - * @webref pshape:mathod - * @usage web_application - * @webBrief Sets the shape to be visible or invisible - * @param visible "false" makes the shape invisible and "true" makes it visible - * @see PShape#isVisible() - */ + /** + * + * Sets the shape to be visible or invisible. This is determined by the value of + * the visible parameter.
+ *
+ * The default visibility of a shape is usually controlled by whatever program + * created the SVG file. For instance, this parameter is controlled by showing + * or hiding the shape in the layers palette in Adobe Illustrator. + * + * @webref pshape:mathod + * @usage web_application + * @webBrief Sets the shape to be visible or invisible + * @param visible "false" makes the shape invisible and "true" makes it visible + * @see PShape#isVisible() + */ public void setVisible(boolean visible) { this.visible = visible; } diff --git a/core/src/processing/core/PVector.java b/core/src/processing/core/PVector.java index 8d4c5b7d7..8d3d5f180 100644 --- a/core/src/processing/core/PVector.java +++ b/core/src/processing/core/PVector.java @@ -29,38 +29,37 @@ import java.io.Serializable; /** * - * A class to describe a two or three dimensional vector. This datatype - * stores two or three variables that are commonly used as a position, - * velocity, and/or acceleration. Technically, position is a point - * and velocity and acceleration are vectors, but this is - * often simplified to consider all three as vectors. For example, if you - * consider a rectangle moving across the screen, at any given instant it - * has a position (the object's location, expressed as a point.), a - * velocity (the rate at which the object's position changes per time unit, - * expressed as a vector), and acceleration (the rate at which the object's - * velocity changes per time unit, expressed as a vector). Since vectors - * represent groupings of values, we cannot simply use traditional - * addition/multiplication/etc. Instead, we'll need to do some "vector" - * math, which is made easy by the methods inside the PVector - * class.
+ * A class to describe a two or three dimensional vector, specifically a + * Euclidean (also known as geometric) vector. A vector is an entity that has + * both magnitude and direction. The datatype, however, stores the components of + * the vector (x,y for 2D, and x,y,z for 3D). The magnitude and direction can be + * accessed via the methods mag() and heading().
*
- * The methods for this class are extensive. For a complete list, visit the - * developer's reference. + * In many of the Processing examples, you will see PVector used to + * describe a position, velocity, or acceleration. For example, if you consider + * a rectangle moving across the screen, at any given instant it has a position + * (a vector that points from the origin to its location), a velocity (the rate + * at which the object's position changes per time unit, expressed as a vector), + * and acceleration (the rate at which the object's velocity changes per time + * unit, expressed as a vector). Since vectors represent groupings of values, we + * cannot simply use traditional addition/multiplication/etc. Instead, we'll + * need to do some "vector" math, which is made easy by the methods inside the + * PVector class. * * * A class to describe a two or three dimensional vector. *

* The result of all functions are applied to the vector itself, with the * exception of cross(), which returns a new PVector (or writes to a specified - * 'target' PVector). That is, add() will add the contents of one vector to - * this one. Using add() with additional parameters allows you to put the - * result into a new PVector. Functions that act on multiple vectors also - * include static versions. Because creating new objects can be computationally - * expensive, most functions include an optional 'target' PVector, so that a - * new PVector object is not created with each operation. + * 'target' PVector). That is, add() will add the contents of one vector to this + * one. Using add() with additional parameters allows you to put the result into + * a new PVector. Functions that act on multiple vectors also include static + * versions. Because creating new objects can be computationally expensive, most + * functions include an optional 'target' PVector, so that a new PVector object + * is not created with each operation. *

- * Initially based on the Vector3D class by Dan Shiffman. + * Initially based on the Vector3D class by + * Dan Shiffman. * * @webref math * @webBrief A class to describe a two or three dimensional vector. @@ -197,18 +196,18 @@ public class PVector implements Serializable { } - /** - * - * Make a new 2D unit vector with a random direction. If you pass in "this" - * as an argument, it will use the PApplet's random number generator. You can - * also pass in a target PVector to fill. - * - * @webref pvector:method - * @usage web_application - * @return the random PVector - * @webBrief Make a new 2D unit vector with a random direction. - * @see PVector#random3D() - */ + /** + * + * Returns a new 2D unit vector with a random direction. If you pass in + * this as an argument, it will use the PApplet's random number + * generator. + * + * @webref pvector:method + * @usage web_application + * @return the random PVector + * @webBrief Make a new 2D unit vector with a random direction. + * @see PVector#random3D() + */ static public PVector random2D() { return random2D(null, null); } @@ -247,18 +246,18 @@ public class PVector implements Serializable { } - /** - * - * Make a new 3D unit vector with a random direction. If you pass in "this" - * as an argument, it will use the PApplet's random number generator. You can - * also pass in a target PVector to fill. - * - * @webref pvector:method - * @usage web_application - * @return the random PVector - * @webBrief Make a new 3D unit vector with a random direction. - * @see PVector#random2D() - */ + /** + * + * Returns a new 3D unit vector with a random direction. If you pass in + * this as an argument, it will use the PApplet's random number + * generator. + * + * @webref pvector:method + * @usage web_application + * @return the random PVector + * @webBrief Make a new 3D unit vector with a random direction. + * @see PVector#random2D() + */ static public PVector random3D() { return random3D(null, null); } @@ -313,12 +312,13 @@ public class PVector implements Serializable { /** * - * Make a new 2D unit vector from an angle. + * Calculates and returns a new 2D unit vector from the specified angle value + * (in radians). * * * @webref pvector:method * @usage web_application - * @webBrief Make a new 2D unit vector from an angle + * @webBrief Make a new 2D unit vector from an angle * @param angle the angle in radians * @return the new unit PVector */ @@ -345,7 +345,7 @@ public class PVector implements Serializable { /** * - * Gets a copy of the vector, returns a PVector object. + * Copies the components of the vector and returns the result as a PVector. * * * @webref pvector:method @@ -400,15 +400,14 @@ public class PVector implements Serializable { /** * - * Calculates the squared magnitude of the vector and returns the result - * as a float (this is simply the equation (x*x + y*y + z*z).) - * Faster if the real length is not required in the - * case of comparing vectors, etc. + * Calculates the magnitude (length) of the vector, squared. This method is + * often used to improve performance since, unlike mag(), it does not + * require a sqrt() operation. * * * @webref pvector:method * @usage web_application - * @webBrief Calculate the magnitude of the vector, squared + * @webBrief Calculate the magnitude of the vector, squared * @return squared magnitude of the vector * @see PVector#mag() */ @@ -419,17 +418,17 @@ public class PVector implements Serializable { /** * - * Adds x, y, and z components to a vector, adds one vector to another, or - * adds two independent vectors together. The version of the method that - * adds two vectors together is a static method and returns a PVector, the - * others have no return value -- they act directly on the vector. See the - * examples for more context. + * Adds x, y, and z components to a vector, adds one vector to another, or adds + * two independent vectors together. The version of the method that adds two + * vectors together is a static method and returns a new PVector, the others act + * directly on the vector itself. See the examples for more context. * * * @webref pvector:method * @usage web_application * @param v the vector to be added - * @webBrief Adds x, y, and z components to a vector, one vector to another, or two independent vectors + * @webBrief Adds x, y, and z components to a vector, one vector to another, or + * two independent vectors */ public PVector add(PVector v) { x += v.x; @@ -487,17 +486,18 @@ public class PVector implements Serializable { /** * - * Subtracts x, y, and z components from a vector, subtracts one vector - * from another, or subtracts two independent vectors. The version of the - * method that subtracts two vectors is a static method and returns a - * PVector, the others have no return value -- they act directly on the - * vector. See the examples for more context. + * Subtracts x, y, and z components from a vector, subtracts one vector from + * another, or subtracts two independent vectors. The version of the method that + * substracts two vectors is a static method and returns a PVector, the others + * act directly on the vector. See the examples for more context. In all cases, + * the second vector (v2) is subtracted from the first (v1), resulting in v1-v2. * * * @webref pvector:method * @usage web_application * @param v any variable of type PVector - * @webBrief Subtract x, y, and z components from a vector, one vector from another, or two independent vectors + * @webBrief Subtract x, y, and z components from a vector, one vector from + * another, or two independent vectors */ public PVector sub(PVector v) { x -= v.x; @@ -555,12 +555,16 @@ public class PVector implements Serializable { /** * - * Multiplies a vector by a scalar or multiplies one vector by another. + * Multiplies a vector by a scalar. The version of the method that uses a float + * acts directly on the vector upon which it is called (as in the first example + * above). The versions that receive both a PVector and a float as arguments are + * static methods, and each returns a new PVector that is the result of the + * multiplication operation. Both examples above produce the same visual output. * * * @webref pvector:method * @usage web_application - * @webBrief Multiply a vector by a scalar + * @webBrief Multiply a vector by a scalar * @param n the number to multiply with the vector */ public PVector mult(float n) { @@ -595,12 +599,15 @@ public class PVector implements Serializable { /** * - * Divides a vector by a scalar or divides one vector by another. - * + * Divides a vector by a scalar. The version of the method that uses a float + * acts directly on the vector upon which it is called (as in the first example + * above). The version that receives both a PVector and a float as arguments is + * a static methods, and returns a new PVector that is the result of the + * division operation. Both examples above produce the same visual output. * * @webref pvector:method * @usage web_application - * @webBrief Divide a vector by a scalar + * @webBrief Divide a vector by a scalar * @param n the number by which to divide the vector */ public PVector div(float n) { @@ -880,18 +887,32 @@ public class PVector implements Serializable { } - /** - * - * Linear interpolate the vector to another vector - * - * - * @webref pvector:method - * @usage web_application - * @webBrief Linear interpolate the vector to another vector - * @param v the vector to lerp to - * @param amt The amount of interpolation; some value between 0.0 (old vector) and 1.0 (new vector). 0.1 is very near the old vector; 0.5 is halfway in between. - * @see PApplet#lerp(float, float, float) - */ + /** + * + * Calculates linear interpolation from one vector to another vector. (Just like + * regular lerp(), but for vectors.)
+ *
+ * Note that there is one static version of this method, and two + * non-static versions. The static version, lerp(v1, v2, amt) is + * given the two vectors to interpolate and returns a new PVector object. The + * static version is used by referencing the PVector class directly. (See the + * middle example above.) The non-static versions, lerp(v, amt) and + * lerp(x, y, z, amt), do not create a new PVector, but transform the + * values of the PVector on which they are called. These non-static versions + * perform the same operation, but the former takes another vector as input, + * while the latter takes three float values. (See the top and bottom examples + * above, respectively.) + * + * + * @webref pvector:method + * @usage web_application + * @webBrief Linear interpolate the vector to another vector + * @param v the vector to lerp to + * @param amt The amount of interpolation; some value between 0.0 (old vector) + * and 1.0 (new vector). 0.1 is very near the old vector; 0.5 is + * halfway in between. + * @see PApplet#lerp(float, float, float) + */ public PVector lerp(PVector v, float amt) { x = PApplet.lerp(x, v.x, amt); y = PApplet.lerp(y, v.y, amt); @@ -971,14 +992,14 @@ public class PVector implements Serializable { /** * - * Return a representation of this vector as a float array. This is only - * for temporary use. If used in any other fashion, the contents should be - * copied by using the PVector.get() method to copy into your own array. + * Return a representation of this vector as a float array. This is only for + * temporary use. If used in any other fashion, the contents should be copied by + * using the copy() method to copy into your own array. * * * @webref pvector:method * @usage: web_application - * @webBrief Return a representation of the vector as a float array + * @webBrief Return a representation of the vector as a float array */ public float[] array() { if (array == null) { diff --git a/core/src/processing/data/FloatDict.java b/core/src/processing/data/FloatDict.java index f79d84ddd..4362c01e8 100644 --- a/core/src/processing/data/FloatDict.java +++ b/core/src/processing/data/FloatDict.java @@ -9,10 +9,12 @@ import processing.core.PApplet; /** - * A simple table class to use a String as a lookup for an float value. + * A simple class to use a String as a lookup for an float value. String "keys" + * are associated with floating-point values. * * @webref data:composite - * @webBrief A simple table class to use a String as a lookup for an float value. + * @webBrief A simple table class to use a String as a lookup for an float + * value. * @see IntDict * @see StringDict */ @@ -109,7 +111,7 @@ public class FloatDict { /** - * Returns the number of key/value pairs + * Returns the number of key/value pairs. * * @webref floatdict:method * @webBrief Returns the number of key/value pairs @@ -145,7 +147,7 @@ public class FloatDict { /** - * Remove all entries. + * Remove all entries from the data structure. * * @webref floatdict:method * @webBrief Remove all entries @@ -258,12 +260,13 @@ public class FloatDict { } - /** - * Return a copy of the internal keys array. This array can be modified. - * - * @webref floatdict:method - * @webBrief Return a copy of the internal keys array - */ + /** + * Return a copy of the internal keys array. In contrast to the keys() + * method, this array can be modified. + * + * @webref floatdict:method + * @webBrief Return a copy of the internal keys array + */ public String[] keyArray() { crop(); return keyArray(null); @@ -285,7 +288,7 @@ public class FloatDict { /** - * Return the internal array being used to store the values + * Return the internal array being used to store the values. * * @webref floatdict:method * @webBrief Return the internal array being used to store the values @@ -321,12 +324,16 @@ public class FloatDict { } - /** - * Create a new array and copy each of the values into it. - * - * @webref floatdict:method - * @webBrief Create a new array and copy each of the values into it - */ + /** + * The version of this method without a parameter creates a new array and copies + * each of the values into it. The version with the float[] parameters + * fills an already-allocated array with the values (more efficient than + * creating a new array each time). If 'array' is null, or not the same size as + * the number of values, a new array will be allocated and returned. + * + * @webref floatdict:method + * @webBrief Create a new array and copy each of the values into it + */ public float[] valueArray() { crop(); return valueArray(null); @@ -372,7 +379,7 @@ public class FloatDict { /** - * Create a new key/value pair or change the value of one + * Create a new key/value pair or change the value of one. * * @webref floatdict:method * @webBrief Create a new key/value pair or change the value of one @@ -397,7 +404,7 @@ public class FloatDict { /** - * Check if a key is a part of the data structure + * Check if a key is a part of the data structure. * * @webref floatdict:method * @webBrief Check if a key is a part of the data structure @@ -407,12 +414,13 @@ public class FloatDict { } - /** - * Add to a value - * - * @webref floatdict:method - * @webBrief Add to a value - */ + /** + * Add to a value. If the key does not exist, an new pair is initialized with + * the value supplied. + * + * @webref floatdict:method + * @webBrief Add to a value + */ public void add(String key, float amount) { int index = index(key); if (index == -1) { @@ -424,7 +432,7 @@ public class FloatDict { /** - * Subtract from a value + * Subtract from a value. * * @webref floatdict:method * @webBrief Subtract from a value @@ -435,7 +443,7 @@ public class FloatDict { /** - * Multiply a value + * Multiply a value. * * @webref floatdict:method * @webBrief Multiply a value @@ -449,7 +457,7 @@ public class FloatDict { /** - * Divide a value + * Divide a value. * * @webref floatdict:method * @webBrief Divide a value @@ -626,7 +634,7 @@ public class FloatDict { /** - * Remove a key/value pair + * Remove a key/value pair. * * @webref floatdict:method * @webBrief Remove a key/value pair @@ -685,19 +693,20 @@ public class FloatDict { } - /** - * Sort the keys alphabetically in reverse - * - * @webref floatdict:method - * @webBrief Sort the keys alphabetically in reverse - */ + /** + * Sort the keys alphabetically in reverse (ignoring case). Uses the value as a + * tie-breaker (only really possible with a key that has a case change). + * + * @webref floatdict:method + * @webBrief Sort the keys alphabetically in reverse + */ public void sortKeysReverse() { sortImpl(true, true, true); } /** - * Sort by values in descending order (largest value will be at [0]). + * Sort by values in ascending order (largest value will be at [0]). * * @webref floatdict:method * @webBrief Sort by values in ascending order @@ -718,7 +727,7 @@ public class FloatDict { /** - * Sort by values in descending order + * Sort by values in descending order. The largest value will be at [0]. * * @webref floatdict:method * @webBrief Sort by values in descending order diff --git a/core/src/processing/data/FloatList.java b/core/src/processing/data/FloatList.java index b563427b2..2816c2662 100644 --- a/core/src/processing/data/FloatList.java +++ b/core/src/processing/data/FloatList.java @@ -159,9 +159,7 @@ public class FloatList implements Iterable { /** - * Set the entry at a particular index. If the index is past the length of - * the list, it'll expand the list to accommodate, and fill the intermediate - * entries with 0s. + * Set the entry at a particular index. * * @webref floatlist:method * @webBrief Set the entry at a particular index @@ -467,7 +465,7 @@ public class FloatList implements Iterable { /** - * Check if a number is a part of the list + * Check if a number is a part of the list. * * @webref floatlist:method * @webBrief Check if a number is a part of the list @@ -498,7 +496,7 @@ public class FloatList implements Iterable { /** - * Add to a value + * Add to a value. * * @webref floatlist:method * @webBrief Add to a value @@ -665,7 +663,7 @@ public class FloatList implements Iterable { /** - * Sorts the array in place. + * Sorts an array, lowest to highest * * @webref floatlist:method * @webBrief Sorts an array, lowest to highest @@ -676,10 +674,11 @@ public class FloatList implements Iterable { /** - * Reverse sort, orders values from highest to lowest + * A sort in reverse. It's equivalent to running sort() and then + * reverse(), but is more efficient than running each separately. * * @webref floatlist:method - * @webBrief Reverse sort, orders values from highest to lowest + * @webBrief A sort in reverse. */ public void sortReverse() { new Sort() { @@ -743,10 +742,10 @@ public class FloatList implements Iterable { /** - * Reverse the order of the list elements + * Reverse the order of the list * * @webref floatlist:method - * @webBrief Reverse the order of the list elements + * @webBrief Reverse the order of the list */ public void reverse() { int ii = count - 1; @@ -760,8 +759,7 @@ public class FloatList implements Iterable { /** - * Randomize the order of the list elements. Note that this does not - * obey the randomSeed() function in PApplet. + * Randomize the order of the list elements. * * @webref floatlist:method * @webBrief Randomize the order of the list elements diff --git a/core/src/processing/data/IntDict.java b/core/src/processing/data/IntDict.java index 3190c84b1..76d5911c1 100644 --- a/core/src/processing/data/IntDict.java +++ b/core/src/processing/data/IntDict.java @@ -9,7 +9,8 @@ import processing.core.PApplet; /** - * A simple class to use a String as a lookup for an int value. + * A simple class to use a String as a lookup for an int value. String "keys" are + * associated with integer values. * * @webref data:composite * @webBrief A simple class to use a String as a lookup for an int value. @@ -142,10 +143,10 @@ public class IntDict { /** - * Remove all entries. + * Remove all entries from the data structure. * * @webref intdict:method - * @webBrief Remove all entries + * @webBrief Remove all entries from the data structure */ public void clear() { count = 0; @@ -256,7 +257,8 @@ public class IntDict { /** - * Return a copy of the internal keys array. This array can be modified. + * Return a copy of the internal keys array. In contrast to the keys() + * method, this array can be modified. * * @webref intdict:method * @webBrief Return a copy of the internal keys array @@ -282,6 +284,8 @@ public class IntDict { /** + * Return the internal array being used to store the values. + * * @webref intdict:method * @webBrief Return the internal array being used to store the values */ @@ -316,12 +320,16 @@ public class IntDict { } - /** - * Create a new array and copy each of the values into it. - * - * @webref intdict:method - * @webBrief Create a new array and copy each of the values into it - */ + /** + * The version of this method without a parameter creates a new array and copies + * each of the values into it. The version with the int[] parameters + * fills an already-allocated array with the values (more efficient than + * creating a new array each time). If 'array' is null, or not the same size as + * the number of values, a new array will be allocated and returned. + * + * @webref intdict:method + * @webBrief Create a new array and copy each of the values into it + */ public int[] valueArray() { crop(); return valueArray(null); @@ -392,6 +400,8 @@ public class IntDict { /** + * Check if a key is a part of the data structure. + * * @webref intdict:method * @webBrief Check if a key is a part of the data structure */ @@ -401,7 +411,7 @@ public class IntDict { /** - * Increase the value associated with a specific key by 1. + * Increase the value of a specific key value by 1 * * @webref intdict:method * @webBrief Increase the value of a specific key value by 1 @@ -424,6 +434,9 @@ public class IntDict { /** + * Add to a value. If the key does not exist, an new pair is initialized + * with the value supplied. + * * @webref intdict:method * @webBrief Add to a value */ @@ -438,6 +451,8 @@ public class IntDict { /** + * Subtract from a value. + * * @webref intdict:method * @webBrief Subtract from a value */ @@ -447,6 +462,8 @@ public class IntDict { /** + * Multiply a value. + * * @webref intdict:method * @webBrief Multiply a value */ @@ -459,6 +476,8 @@ public class IntDict { /** + * Divide a value. + * * @webref intdict:method * @webBrief Divide a value */ @@ -590,6 +609,8 @@ public class IntDict { } /** + * Remove a key/value pair. + * * @webref intdict:method * @webBrief Remove a key/value pair */ diff --git a/core/src/processing/data/IntList.java b/core/src/processing/data/IntList.java index f859145de..51af0ecb5 100644 --- a/core/src/processing/data/IntList.java +++ b/core/src/processing/data/IntList.java @@ -178,9 +178,7 @@ public class IntList implements Iterable { /** - * Set the entry at a particular index. If the index is past the length of - * the list, it'll expand the list to accommodate, and fill the intermediate - * entries with 0s. + * Set the entry at a particular index. * * @webref intlist:method * @webBrief Set the entry at a particular index @@ -444,6 +442,8 @@ public class IntList implements Iterable { // } /** + * Check if a number is a part of the data structure. + * * @webref intlist:method * @webBrief Check if a number is a part of the list */ @@ -461,6 +461,8 @@ public class IntList implements Iterable { } /** + * Add one to a value. + * * @webref intlist:method * @webBrief Add one to a value */ @@ -480,6 +482,8 @@ public class IntList implements Iterable { /** + * Add to a value. + * * @webref intlist:method * @webBrief Add to a value */ @@ -492,6 +496,8 @@ public class IntList implements Iterable { } /** + * Subtract from a value. + * * @webref intlist:method * @webBrief Subtract from a value */ @@ -504,6 +510,8 @@ public class IntList implements Iterable { } /** + * Multiply a value. + * * @webref intlist:method * @webBrief Multiply a value */ @@ -516,6 +524,8 @@ public class IntList implements Iterable { } /** + * Divide a value. + * * @webref intlist:method * @webBrief Divide a value */ @@ -539,6 +549,8 @@ public class IntList implements Iterable { /** + * Return the smallest value. + * * @webref intlist:method * @webBrief Return the smallest value */ @@ -569,6 +581,8 @@ public class IntList implements Iterable { /** + * Return the largest value. + * * @webref intlist:method * @webBrief Return the largest value */ @@ -620,7 +634,7 @@ public class IntList implements Iterable { /** - * Sorts the array in place. + * Sorts the array, lowest to highest. * * @webref intlist:method * @webBrief Sorts the array, lowest to highest @@ -631,7 +645,8 @@ public class IntList implements Iterable { /** - * Reverse sort, orders values from highest to lowest. + * A sort in reverse. It's equivalent to running sort() and then + * reverse(), but is more efficient than running each separately. * * @webref intlist:method * @webBrief Reverse sort, orders values from highest to lowest @@ -676,6 +691,8 @@ public class IntList implements Iterable { // } /** + * Reverse the order of the list. + * * @webref intlist:method * @webBrief Reverse the order of the list elements */ @@ -691,8 +708,7 @@ public class IntList implements Iterable { /** - * Randomize the order of the list elements. Note that this does not - * obey the randomSeed() function in PApplet. + * Randomize the order of the list elements. * * @webref intlist:method * @webBrief Randomize the order of the list elements diff --git a/core/src/processing/data/JSONArray.java b/core/src/processing/data/JSONArray.java index bc410a7d4..a99618c78 100644 --- a/core/src/processing/data/JSONArray.java +++ b/core/src/processing/data/JSONArray.java @@ -46,6 +46,10 @@ import java.util.ArrayList; import processing.core.PApplet; /** + * A JSONArray stores an array of JSON objects. JSONArrays can + * be generated from scratch, dynamically, or using data from an existing file. + * JSON can also be output and saved to disk, as in the example above. + * * A JSONArray is an ordered sequence of values. Its external text form is a * string wrapped in square brackets with commas separating the values. The * internal form is an object having get and opt @@ -274,7 +278,7 @@ public class JSONArray { /** - * Get the string associated with an index. + * Gets the String value associated with the specified index. * * @webref jsonarray:method * @webBrief Gets the String value associated with an index @@ -309,10 +313,10 @@ public class JSONArray { /** - * Get the int value associated with an index. + * Gets the int value associated with the specified index. * * @webref jsonarray:method - * @webBrief Gets the int value associated with an index + * @webBrief Gets the int value associated with the specified index. * @param index must be between 0 and length() - 1 * @return The value. * @throws RuntimeException If the key is not found or if the value is not a number. @@ -387,11 +391,10 @@ public class JSONArray { /** - * Get a value from an index as a float. JSON uses 'double' values - * internally, so this is simply getDouble() cast to a float. + * Gets the float value associated with the specified index. * * @webref jsonarray:method - * @webBrief Gets the float value associated with an index + * @webBrief Gets the float value associated with the specified index. * @param index must be between 0 and length() - 1 * @see JSONArray#getInt(int) * @see JSONArray#getString(int) @@ -450,11 +453,10 @@ public class JSONArray { /** - * Get the boolean value associated with an index. - * The string values "true" and "false" are converted to boolean. + * Gets the boolean value associated with the specified index. * * @webref jsonarray:method - * @webBrief Gets the boolean value associated with an index + * @webBrief Gets the boolean value associated with the specified index. * @param index must be between 0 and length() - 1 * @return The truth. * @throws RuntimeException If there is no value for the index or if the @@ -497,10 +499,10 @@ public class JSONArray { /** - * Get the JSONArray associated with an index. + * Retrieves the JSONArray with the associated index value. * * @webref jsonobject:method - * @webBrief Gets the JSONArray associated with an index value + * @webBrief Retrieves the JSONArray with the associated index value. * @param index must be between 0 and length() - 1 * @return A JSONArray value. * @throws RuntimeException If there is no value for the index. or if the @@ -528,10 +530,10 @@ public class JSONArray { /** - * Get the JSONObject associated with an index. + * Retrieves the JSONObject with the associated index value. * * @webref jsonobject:method - * @webBrief Gets the JSONObject associated with an index value + * @webBrief Retrieves the JSONObject with the associated index value. * @param index the index value of the object to get * @return A JSONObject value. * @throws RuntimeException If there is no value for the index or if the @@ -559,10 +561,11 @@ public class JSONArray { /** - * Get this entire array as a String array. + * Returns the entire JSONArray as an array of Strings. + * (All values in the array must be of the String type.) * * @webref jsonarray:method - * @webBrief Gets the entire array as an array of Strings + * @webBrief Returns the entire JSONArray as an array of Strings * @see JSONArray#getIntArray() */ public String[] getStringArray() { @@ -575,10 +578,11 @@ public class JSONArray { /** - * Get this entire array as an int array. Everything must be an int. + * Returns the entire JSONArray as an array of ints. + * (All values in the array must be of the int type.) * * @webref jsonarray:method - * @webBrief Gets the entire array as array of ints + * @webBrief Returns the entire JSONArray as an array of ints * @see JSONArray#getStringArray() */ public int[] getIntArray() { @@ -696,7 +700,9 @@ public class JSONArray { /** - * Append an String value. This increases the array's length by one. + * Appends a new value to the JSONArray, increasing the array's length + * by one. New values may be of the following types: int, float, String, + * boolean, JSONObject, or JSONArray. * * @webref jsonarray:method * @webBrief Appends a value, increasing the array's length by one @@ -848,12 +854,14 @@ public class JSONArray { /** - * Put or replace a String value. If the index is greater than the length of - * the JSONArray, then null elements will be added as necessary to pad - * it out. + * Inserts a new value into the JSONArray at the specified index + * position. If a value already exists in the specified position, the new + * value overwrites the old value. If the given index is greater than the + * length of the JSONArray, then null elements will be added as + * necessary to pad it out. * * @webref jsonarray:method - * @webBrief Put a String value in the JSONArray + * @webBrief Inserts a new value into the JSONArray at the specified index position. * @param index an index value * @param value the value to assign * @return this. @@ -869,9 +877,11 @@ public class JSONArray { /** - * Put or replace an int value. If the index is greater than the length of - * the JSONArray, then null elements will be added as necessary to pad - * it out. + * Inserts a new value into the JSONArray at the specified index + * position. If a value already exists in the specified position, the + * new value overwrites the old value. If the given index is greater + * than the length of the JSONArray, then null elements will be + * added as necessary to pad it out. * * @webref jsonarray:method * @webBrief Put an int value in the JSONArray @@ -904,10 +914,11 @@ public class JSONArray { /** - * Put or replace a float value. If the index is greater than the length - * of the JSONArray, then null elements will be added as necessary to pad - * it out. There are no 'double' values in JSON, so this is passed to - * setDouble(value). + * Inserts a new value into the JSONArray at the specified index + * position. If a value already exists in the specified position, the + * new value overwrites the old value. If the given index is greater + * than the length of the JSONArray, then null elements will be + * added as necessary to pad it out. * * @webref jsonarray:method * @webBrief Put a float value in the JSONArray @@ -941,12 +952,14 @@ public class JSONArray { /** - * Put or replace a boolean value in the JSONArray. If the index is greater - * than the length of the JSONArray, then null elements will be added as - * necessary to pad it out. + * Inserts a new value into the JSONArray at the specified index + * position. If a value already exists in the specified position, the + * new value overwrites the old value. If the given index is greater + * than the length of the JSONArray, then null elements will be + * added as necessary to pad it out. * * @webref jsonarray:method - * @webBrief Put a boolean value in the JSONArray + * @webBrief Inserts a new value into the JSONArray at the specified index position * @param index an index value * @param value the value to assign * @return this. @@ -975,10 +988,10 @@ public class JSONArray { // } /** - * Sets the JSONArray value associated with an index value + * Sets the value of the JSONArray with the associated index value. * * @webref jsonarray:method - * @webBrief Sets the JSONArray value associated with an index value + * @webBrief Sets the value of the JSONArray with the associated index value * @param index the index value to target * @param value the value to assign * @see JSONArray#setJSONObject(int, JSONObject) @@ -991,10 +1004,10 @@ public class JSONArray { } /** - * Sets the JSONObject value associated with an index value + * Sets the value of the JSONObject with the index value. * * @webref jsonarray:method - * @webBrief Sets the JSONObject value associated with an index value + * @webBrief Sets the value of the JSONObject with the index value * @param index the index value to target * @param value the value to assign * @see JSONArray#setJSONArray(int, JSONArray) @@ -1037,10 +1050,10 @@ public class JSONArray { /** - * Get the number of elements in the JSONArray, included nulls. + * Gets the total number of elements in a JSONArray (inclusive of null elements). * * @webref jsonarray:method - * @webBrief Gets the number of elements in the JSONArray + * @webBrief Gets the total number of elements in a JSONArray * @return The length (or size). * @see JSONArray#append(String) * @see JSONArray#remove(int) @@ -1051,9 +1064,11 @@ public class JSONArray { /** - * Determine if the value is null. + * Determines if the value associated with the index is null, that is has + * no defined value (false) or if it has a value (true). + * * @webref - * @webBrief Determine if the value is null. + * @webBrief Determines if the value associated with the index is null * @param index must be between 0 and length() - 1 * @return true if the value at the index is null, or if there is no value. */ @@ -1063,10 +1078,12 @@ public class JSONArray { /** - * Remove an index and close the hole. + * Removes the element from a JSONArray in the specified index position. + * Returns either the value associated with the given index, or null, if there + * is no value. * * @webref jsonarray:method - * @webBrief Removes an element + * @webBrief Removes the element from a JSONArray in the specified index position * @param index the index value of the element to be removed * @return The value that was associated with the index, or null if there was no value. * @see JSONArray#size() diff --git a/core/src/processing/data/JSONObject.java b/core/src/processing/data/JSONObject.java index 139c861d4..7b7152a3b 100644 --- a/core/src/processing/data/JSONObject.java +++ b/core/src/processing/data/JSONObject.java @@ -51,6 +51,18 @@ import java.util.Set; import processing.core.PApplet; /** + * A JSONObject stores JSON data with multiple name/value pairs. Values + * can be numeric, Strings, booleans, other JSONObjects or + * JSONArrays, or null. JSONObject and JSONArray objects + * are quite similar and share most of the same methods; the primary difference + * is that the latter stores an array of JSON objects, while the former + * represents a single JSON object.
+ *
+ * JSON can be generated from scratch, dynamically, or using data from an + * existing file. JSON can also be output and saved to disk, as in the example + * above. + * + * * A JSONObject is an unordered collection of name/value pairs. Its external * form is a string wrapped in curly braces with colons between the names and * values, and commas between the values and names. The internal form is an @@ -555,10 +567,10 @@ public class JSONObject { /** - * Gets the String associated with a key + * Gets the String value associated with the specified key. * * @webref jsonobject:method - * @webBrief Gets the string value associated with a key + * @webBrief Gets the String value associated with the specified key * @param key a key string * @return A string which is the value. * @throws RuntimeException if there is no string value for the key. @@ -594,10 +606,10 @@ public class JSONObject { /** - * Gets the int value associated with a key + * Gets the int value associated with the specified key. * * @webref jsonobject:method - * @webBrief Gets the int value associated with a key + * @webBrief Gets the int value associated with the specified key * @param key A key string. * @return The integer value. * @throws RuntimeException if the key is not found or if the value cannot @@ -679,7 +691,7 @@ public class JSONObject { /** - * Gets the float value associated with a key + * Gets the float value associated with the specified key * * @webref jsonobject:method * @webBrief Gets the float value associated with a key @@ -741,10 +753,10 @@ public class JSONObject { /** - * Get the boolean value associated with a key. + * Gets the boolean value associated with the specified key. * * @webref jsonobject:method - * @webBrief Gets the boolean value associated with a key + * @webBrief Gets the boolean value associated with the specified key * @param key a key string * @return The truth. * @throws RuntimeException if the value is not a Boolean or the String "true" or "false". @@ -786,10 +798,10 @@ public class JSONObject { /** - * Get the JSONArray value associated with a key. + * Retrieves the JSONArray with the associated key. * * @webref jsonobject:method - * @webBrief Gets the JSONArray value associated with a key + * @webBrief Retrieves the JSONArray with the associated key * @param key a key string * @return A JSONArray which is the value, or null if not present * @throws RuntimeException if the value is not a JSONArray. @@ -810,10 +822,10 @@ public class JSONObject { /** - * Get the JSONObject value associated with a key. + * Given a key value, retrieves the associated JSONObject. * * @webref jsonobject:method - * @webBrief Gets the JSONObject value associated with a key + * @webBrief Given a key value, retrieves the associated JSONObject * @param key a key string * @return A JSONObject which is the value or null if not available. * @throws RuntimeException if the value is not a JSONObject. @@ -916,12 +928,12 @@ public class JSONObject { /** - * Determine if the value associated with the key is null or if there is - * no value. + * Determines if the value associated with the key is null, that is has + * no defined value (false) or if it has a value (true). * * @webref - * @webBrief Determine if the value associated with the key is null or if there is - * no value. + * @webBrief Determines if the value associated with the key is null, that is has + * no defined value (false) or if it has a value (true). * @param key A key string. * @return true if there is no value associated with the key or if * the value is the JSONObject.NULL object. @@ -1161,8 +1173,11 @@ public class JSONObject { /** + * Inserts a new key/String pair into the JSONObject or, if a value with + * the specified key already exists, assigns a new value. + * * @webref jsonobject:method - * @webBrief Put a key/String pair in the JSONObject + * @webBrief Inserts a new key/String pair into the JSONObject * @param key a key string * @param value the value to assign * @see JSONObject#setInt(String, int) @@ -1175,10 +1190,11 @@ public class JSONObject { /** - * Put a key/int pair in the JSONObject. - * + * Inserts a new key/int pair into the JSONObject or, if a value with + * the specified key already exists, assigns a new value. + * * @webref jsonobject:method - * @webBrief Put a key/int pair in the JSONObject + * @webBrief Inserts a new key/int pair into the JSONObject * @param key a key string * @param value the value to assign * @return this. @@ -1207,7 +1223,8 @@ public class JSONObject { } /** - * Put a key/float pair in the JSONObject + * Inserts a new key/float pair into the JSONObject or, if a value with + * the specified key already exists, assigns a new value. * * @webref jsonobject:method * @webBrief Put a key/float pair in the JSONObject @@ -1239,7 +1256,8 @@ public class JSONObject { /** - * Put a key/boolean pair in the JSONObject. + * Inserts a new key/boolean pair into the JSONObject or, if a value + * with the specified key already exists, assigns a new value. * * @webref jsonobject:method * @webBrief Put a key/boolean pair in the JSONObject @@ -1257,10 +1275,10 @@ public class JSONObject { } /** - * Sets the JSONObject value associated with a key + * Sets the value of the JSONObject with the associated key. * * @webref jsonobject:method - * @webBrief Sets the JSONObject value associated with a key + * @webBrief Sets the value of the JSONObject with the associated key * @param key a key string * @param value value to assign * @see JSONObject#setJSONArray(String, JSONArray) @@ -1272,10 +1290,10 @@ public class JSONObject { } /** - * Sets the JSONArray value associated with a key + * Sets the value of the JSONArray with the associated key. * * @webref jsonobject:method - * @webBrief Sets the JSONArray value associated with a key + * @webBrief Sets the value of the JSONArray with the associated key * @param key a key string * @param value value to assign * @see JSONObject#setJSONObject(String, JSONObject) diff --git a/core/src/processing/data/StringDict.java b/core/src/processing/data/StringDict.java index 32b241afc..97e2e4d72 100644 --- a/core/src/processing/data/StringDict.java +++ b/core/src/processing/data/StringDict.java @@ -9,10 +9,11 @@ import processing.core.PApplet; /** - * A simple table class to use a String as a lookup for another String value. + * A simple class to use a String as a lookup for an String value. String "keys" + * are associated with String values. * * @webref data:composite - * @webBrief A simple table class to use a String as a lookup for another String value. + * @webBrief A simple class to use a String as a lookup for an String value * @see IntDict * @see FloatDict */ @@ -279,7 +280,7 @@ public class StringDict { /** - * Return a copy of the internal keys array. This array can be modified. + * Return a copy of the internal keys array. * * @webref stringdict:method * @webBrief Return a copy of the internal keys array @@ -489,8 +490,7 @@ public class StringDict { /** - * Sort the keys alphabetically (ignoring case). Uses the value as a - * tie-breaker (only really possible with a key that has a case change). + * Sort the keys alphabetically. * * @webref stringdict:method * @webBrief Sort the keys alphabetically @@ -511,10 +511,10 @@ public class StringDict { /** - * Sort by values in descending order (largest value will be at [0]). + * Sort by values in descending order. * * @webref stringdict:method - * @webBrief Sort by values in ascending order + * @webBrief Sort by values in descending order */ public void sortValues() { sortImpl(false, false); diff --git a/core/src/processing/data/StringList.java b/core/src/processing/data/StringList.java index 57409047c..f69c1a7ea 100644 --- a/core/src/processing/data/StringList.java +++ b/core/src/processing/data/StringList.java @@ -149,7 +149,7 @@ public class StringList implements Iterable { /** * Set the entry at a particular index. If the index is past the length of * the list, it'll expand the list to accommodate, and fill the intermediate - * entries with 0s. + * entries with "null". * * @webref stringlist:method * @webBrief Set an entry at a particular index @@ -503,10 +503,11 @@ public class StringList implements Iterable { /** - * Reverse sort, orders values from highest to lowest. + * A sort in reverse. It's equivalent to running sort() and then + * reverse(), but is more efficient than running each separately. * * @webref stringlist:method - * @webBrief Reverse sort, orders values from highest to lowest + * @webBrief A sort in reverse */ public void sortReverse() { sortImpl(true); @@ -554,10 +555,10 @@ public class StringList implements Iterable { // } /** - * Reverse the order of the list elements + * Reverse the order of the list * * @webref stringlist:method - * @webBrief Reverse the order of the list elements + * @webBrief Reverse the order of the list */ public void reverse() { int ii = count - 1; @@ -571,8 +572,7 @@ public class StringList implements Iterable { /** - * Randomize the order of the list elements. Note that this does not - * obey the randomSeed() function in PApplet. + * Randomize the order of the list elements. * * @webref stringlist:method * @webBrief Randomize the order of the list elements diff --git a/core/src/processing/data/Table.java b/core/src/processing/data/Table.java index 787e29c2f..9c2abae02 100644 --- a/core/src/processing/data/Table.java +++ b/core/src/processing/data/Table.java @@ -46,18 +46,36 @@ import processing.core.PConstants; /** - *

Generic class for handling tabular data, typically from a CSV, TSV, or - * other sort of spreadsheet file.

- *

CSV files are - * comma separated values, - * often with the data in quotes. TSV files use tabs as separators, and usually - * don't bother with the quotes.

- *

File names should end with .csv if they're comma separated.

- *

A rough "spec" for CSV can be found here.

+ * Table objects store data with multiple rows and columns, much like in + * a traditional spreadsheet. Tables can be generated from scratch, dynamically, + * or using data from an existing file. Tables can also be output and saved to + * disk, as in the example above.
+ *
+ * Additional Table methods are documented in the Processing + * Table Javadoc. + * + *

+ * Generic class for handling tabular data, typically from a CSV, TSV, or other + * sort of spreadsheet file. + *

+ *

+ * CSV files are + * comma separated + * values, often with the data in quotes. TSV files use tabs as separators, + * and usually don't bother with the quotes. + *

+ *

+ * File names should end with .csv if they're comma separated. + *

+ *

+ * A rough "spec" for CSV can be found + * here. + *

* * @webref data:composite - * @webBrief Generic class for handling tabular data, typically from a CSV, TSV, or - * other sort of spreadsheet file. + * @webBrief Generic class for handling tabular data, typically from a CSV, TSV, + * or other sort of spreadsheet file. * @see PApplet#loadTable(String) * @see PApplet#saveTable(Table, String) * @see TableRow @@ -1790,13 +1808,18 @@ public class Table { // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . - /** - * Adds a new column to a table - * - * @webref table:method - * @webBrief Adds a new column to a table - * @see Table#removeColumn(String) - */ + /** + * Use addColumn() to add a new column to a Table object. + * Typically, you will want to specify a title, so the column may be easily + * referenced later by name. (If no title is specified, the new column's title + * will be null.) A column type may also be specified, in which case all values + * stored in this column must be of the same type (e.g., Table.INT or + * Table.FLOAT). If no type is specified, the default type of STRING is used. + * + * @webref table:method + * @webBrief Adds a new column to a table + * @see Table#removeColumn(String) + */ public void addColumn() { addColumn(null, STRING); } @@ -1866,14 +1889,18 @@ public class Table { } } - /** - * Removes a column from a table - * - * @webref table:method - * @webBrief Removes a column from a table - * @param columnName the title of the column to be removed - * @see Table#addColumn() - */ + /** + * Use removeColumn() to remove an existing column from a Table + * object. The column to be removed may be identified by either its title (a + * String) or its index value (an int). removeColumn(0) would remove the + * first column, removeColumn(1) would remove the second column, and so + * on. + * + * @webref table:method + * @webBrief Removes a column from a table + * @param columnName the title of the column to be removed + * @see Table#addColumn() + */ public void removeColumn(String columnName) { removeColumn(getColumnIndex(columnName)); } @@ -1914,10 +1941,10 @@ public class Table { /** - * Gets the number of columns in a table + * Returns the total number of columns in a table. * * @webref table:method - * @webBrief Gets the number of columns in a table + * @webBrief Returns the total number of columns in a table * @see Table#getRowCount() */ public int getColumnCount() { @@ -2264,10 +2291,10 @@ public class Table { // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /** - * Gets the number of rows in a table + * Returns the total number of rows in a table. * * @webref table:method - * @webBrief Gets the number of rows in a table + * @webBrief Returns the total number of rows in a table * @see Table#getColumnCount() */ public int getRowCount() { @@ -2281,10 +2308,11 @@ public class Table { /** - * Removes all rows from a table + * Removes all rows from a Table. While all rows are removed, columns + * and column titles are maintained. * * @webref table:method - * @webBrief Removes all rows from a table + * @webBrief Removes all rows from a Table * @see Table#addRow() * @see Table#removeRow(int) */ @@ -2325,14 +2353,19 @@ public class Table { } - /** - * Adds a row to a table - * - * @webref table:method - * @webBrief Adds a row to a table - * @see Table#removeRow(int) - * @see Table#clearRows() - */ + /** + * Use addRow() to add a new row of data to a Table object. By + * default, an empty row is created. Typically, you would store a reference to + * the new row in a TableRow object (see newRow in the example + * above), and then set individual values using setInt(), + * setFloat(), or setString(). If a TableRow object is + * included as a parameter, then that row is duplicated and added to the table. + * + * @webref table:method + * @webBrief Adds a new row of data to a Table object + * @see Table#removeRow(int) + * @see Table#clearRows() + */ public TableRow addRow() { //if (rowIncrement == 0) { setRowCount(rowCount + 1); @@ -2452,10 +2485,10 @@ public class Table { /** - * Removes a row from a table + * Removes a row from a Table object * * @webref table:method - * @webBrief Removes a row from a table + * @webBrief Removes a row from a Table object * @param row ID number of the row to remove * @see Table#addRow() * @see Table#clearRows() @@ -2660,10 +2693,11 @@ public class Table { // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /** - * Gets a row from a table + * Returns a reference to the specified TableRow. The reference can then + * be used to get and set values of the selected row, as illustrated in the example above. * * @webref table:method - * @webBrief Gets a row from a table + * @webBrief Returns a reference to the specified TableRow * @param row ID number of the row to get * @see Table#rows() * @see Table#findRow(String, int) @@ -2677,12 +2711,11 @@ public class Table { /** - * Note that this one iterator instance is shared by any calls to iterate - * the rows of this table. This is very efficient, but not thread-safe. - * If you want to iterate in a multi-threaded manner, don't use the iterator. + * Gets all rows from the table. Returns an iterator, so for must be + * used to iterate through all the rows, as shown in the example above. * * @webref table:method - * @webBrief Gets multiple rows from a table + * @webBrief Gets all rows from the table * @see Table#getRow(int) * @see Table#findRow(String, int) * @see Table#findRows(String, int) @@ -3069,10 +3102,12 @@ public class Table { /** - * Get an integer value from the specified row and column + * Retrieves an integer value from the Table's specified row and column. + * The row is specified by its ID, while the column may be specified by either + * its ID or title. * * @webref table:method - * @webBrief Get an integer value from the specified row and column + * @webBrief Retrieves an integer value from the Table's specified row and column * @param row ID number of the row to reference * @param column ID number of the column to reference * @see Table#getFloat(int, int) @@ -3108,10 +3143,12 @@ public class Table { /** - * Store an integer value in the specified row and column + * Stores an integer value in the Table's specified row and column. + * The row is specified by its ID, while the column may be specified by + * either its ID or title. * * @webref table:method - * @webBrief Store an integer value in the specified row and column + * @webBrief Stores an integer value in the Table's specified row and column * @param row ID number of the target row * @param column ID number of the target column * @param value value to assign @@ -3249,12 +3286,12 @@ public class Table { /** - * Get a float value from the specified row and column. If the value is null - * or not parseable as a float, the "missing" value is returned. By default, - * this is Float.NaN, but can be controlled with setMissingFloat(). + * Retrieves a float value from the Table's specified row and column. + * The row is specified by its ID, while the column may be specified by either + * its ID or title. * * @webref table:method - * @webBrief Get a float value from the specified row and column + * @webBrief Retrieves a float value from the Table's specified row and column * @param row ID number of the row to reference * @param column ID number of the column to reference * @see Table#getInt(int, int) @@ -3291,10 +3328,12 @@ public class Table { /** - * Store a float value in the specified row and column + * Stores a float value in the Table's specified row and column. + * The row is specified by its ID, while the column may be specified by + * either its ID or title. * * @webref table:method - * @webBrief Store a float value in the specified row and column + * @webBrief Stores a float value in the Table's specified row and column * @param row ID number of the target row * @param column ID number of the target column * @param value value to assign @@ -3486,10 +3525,12 @@ public class Table { /** - * Get a String value from the table. If the row is longer than the table + * Retrieves a String value from the Table's specified row and column. + * The row is specified by its ID, while the column may be specified by either + * its ID or title. * * @webref table:method - * @webBrief Get an String value from the specified row and column + * @webBrief Retrieves a String value from the Table's specified row and column * @param row ID number of the row to reference * @param column ID number of the column to reference * @see Table#getInt(int, int) @@ -3540,10 +3581,12 @@ public class Table { /** - * Store a float value in the specified row and column + * Stores a String value in the Table's specified row and column. + * The row is specified by its ID, while the column may be specified by + * either its ID or title. * * @webref table:method - * @webBrief Store a String value in the specified row and column + * @webBrief Stores a String value in the Table's specified row and column * @param row ID number of the target row * @param column ID number of the target column * @param value value to assign @@ -3572,10 +3615,11 @@ public class Table { } /** - * Gets all values in the specified column + * Retrieves all values in the specified column, and returns them as a String + * array. The column may be specified by either its ID or title. * * @webref table:method - * @webBrief Gets all values in the specified column + * @webBrief Retrieves all values in the specified column * @param columnName title of the column to search * @see Table#getInt(int, int) * @see Table#getFloat(int, int) @@ -3716,7 +3760,10 @@ public class Table { // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /** - * Finds a row that contains the given value + * Finds the first row in the Table that contains the value provided, + * and returns a reference to that row. Even if multiple rows are possible + * matches, only the first matching row is returned. The column to search may + * be specified by either its ID or title. * * @webref table:method * @webBrief Finds a row that contains the given value @@ -3743,7 +3790,10 @@ public class Table { /** - * Finds multiple rows that contain the given value + * Finds the rows in the Table that contain the value provided, + * and returns references to those rows. Returns an iterator, so for + * must be used to iterate through all the rows, as shown in the example above. + * The column to search may be specified by either its ID or title. * * @webref table:method * @webBrief Finds multiple rows that contain the given value @@ -3877,7 +3927,10 @@ public class Table { // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /** - * Finds a row that matches the given expression + * Finds the first row in the Table that matches the regular expression + * provided, and returns a reference to that row. Even if multiple rows are + * possible matches, only the first matching row is returned. The column to + * search may be specified by either its ID or title. * * @webref table:method * @webBrief Finds a row that matches the given expression @@ -3904,7 +3957,10 @@ public class Table { /** - * Finds multiple rows that match the given expression + * Finds the rows in the Table that match the regular expression provided, + * and returns references to those rows. Returns an iterator, so for + * must be used to iterate through all the rows, as shown in the example above. + * The column to search may be specified by either its ID or title. * * @webref table:method * @webBrief Finds multiple rows that match the given expression @@ -4036,14 +4092,18 @@ public class Table { // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . - /** - * Remove any of the specified characters from the entire table. - * - * @webref table:method - * @webBrief Removes characters from the table - * @param tokens a list of individual characters to be removed - * @see Table#trim() - */ + /** + * Removes any of the specified characters (or "tokens"). The example above + * removes all commas, dollar signs, and spaces from the table.
+ *
+ * If no column is specified, then the values in all columns and rows are + * processed. A specific column may be referenced by either its ID or title. + * + * @webref table:method + * @webBrief Removes characters from the table + * @param tokens a list of individual characters to be removed + * @see Table#trim() + */ public void removeTokens(String tokens) { for (int col = 0; col < getColumnCount(); col++) { removeTokens(tokens, col); @@ -4093,7 +4153,10 @@ public class Table { /** - * Trims whitespace from values + * Trims leading and trailing whitespace, such as spaces and tabs, from String + * table values. If no column is specified, then the values in all columns + * and rows are trimmed. A specific column may be referenced by either its ID + * or title. * * @webref table:method * @webBrief Trims whitespace from values diff --git a/core/src/processing/data/TableRow.java b/core/src/processing/data/TableRow.java index 370cbeefb..45c7816e7 100644 --- a/core/src/processing/data/TableRow.java +++ b/core/src/processing/data/TableRow.java @@ -21,7 +21,8 @@ import java.io.PrintWriter; public interface TableRow { /** - * Get an String value from the specified column + * Retrieves a String value from the TableRow's specified column. + * The column may be specified by either its ID or title. * * @webref tablerow:method * @webBrief Get an String value from the specified column @@ -37,7 +38,8 @@ public interface TableRow { public String getString(String columnName); /** - * Get an integer value from the specified column + * Retrieves an integer value from the TableRow's specified column. + * The column may be specified by either its ID or title. * * @webref tablerow:method * @webBrief Get an integer value from the specified column @@ -67,7 +69,8 @@ public interface TableRow { public long getLong(String columnName); /** - * Get a float value from the specified column + * Retrieves a float value from the TableRow's specified column. + * The column may be specified by either its ID or title. * * @webref tablerow:method * @webBrief Get a float value from the specified column @@ -96,7 +99,8 @@ public interface TableRow { public double getDouble(String columnName); /** - * Store a String value in the specified column + * Stores a String value in the TableRow's specified column. The column + * may be specified by either its ID or title. * * @webref tablerow:method * @webBrief Store a String value in the specified column @@ -112,8 +116,9 @@ public interface TableRow { public void setString(String columnName, String value); /** - * Store an integer value in the specified column - * + * Stores an integer value in the TableRow's specified column. The column + * may be specified by either its ID or title. + * * @webref tablerow:method * @webBrief Store an integer value in the specified column * @param column ID number of the target column @@ -143,7 +148,8 @@ public interface TableRow { public void setLong(String columnName, long value); /** - * Store a float value in the specified column + * Stores a float value in the TableRow's specified column. The column + * may be specified by either its ID or title. * * @webref tablerow:method * @webBrief Store a float value in the specified column @@ -174,7 +180,7 @@ public interface TableRow { public void setDouble(String columnName, double value); /** - * Get the column count. + * Returns the number of columns in a TableRow. * * @webref tablerow:method * @webBrief Get the column count. @@ -201,7 +207,7 @@ public interface TableRow { public int[] getColumnTypes(); /** - * Get the column title. + * Returns the name for a column in a TableRow based on its ID (e.g. 0, 1, 2, etc.) * * @webref tablerow:method * @webBrief Get the column title. diff --git a/core/src/processing/data/XML.java b/core/src/processing/data/XML.java index 61f4a3d05..409f6ac01 100644 --- a/core/src/processing/data/XML.java +++ b/core/src/processing/data/XML.java @@ -41,12 +41,16 @@ import processing.core.PApplet; /** - * This is the base class used for the Processing XML library, - * representing a single node of an XML tree. + * XML is a representation of an XML object, able to parse XML code. Use + * loadXML() to load external XML files and create XML + * objects.
+ *
+ * Only files encoded as UTF-8 (or plain ASCII) are parsed properly; the + * encoding parameter inside XML files is ignored. * * @webref data:composite * @webBrief This is the base class used for the Processing XML library, - * representing a single node of an XML tree. + * representing a single node of an XML tree. * @see PApplet#loadXML(String) * @see PApplet#parseXML(String) * @see PApplet#saveXML(XML, String) @@ -301,8 +305,7 @@ public class XML implements Serializable { /** - * Returns the parent element. This method returns null for the root - * element. + * Gets a copy of the element's parent. Returns the parent as another XML object. * * @webref xml:method * @webBrief Gets a copy of the element's parent @@ -320,8 +323,7 @@ public class XML implements Serializable { /** - * Returns the full name (i.e. the name including an eventual namespace - * prefix) of the element. + * Gets the element's full name, which is returned as a String. * * @webref xml:method * @webBrief Gets the element's full name @@ -333,7 +335,7 @@ public class XML implements Serializable { } /** - * Sets the element's name + * Sets the element's name, which is specified as a String. * * @webref xml:method * @webBrief Sets the element's name @@ -386,7 +388,7 @@ public class XML implements Serializable { /** - * Returns a boolean of whether or not there are children. + * Checks whether or not the element has any children, and returns the result as a boolean. * * @webref xml:method * @webBrief Checks whether or not an element has any children @@ -398,8 +400,9 @@ public class XML implements Serializable { /** - * Put the names of all children into an array. Same as looping through - * each child and calling getName() on each XMLElement. + * Get the names of all of the element's children, and returns the names as an + * array of Strings. This is the same as looping through and calling getName() + * on each child element individually. * * @webref xml:method * @webBrief Returns the names of all children as an array @@ -424,7 +427,10 @@ public class XML implements Serializable { /** - * Returns an array containing all the child elements. + * Returns all of the element's children as an array of XML objects. When + * the name parameter is specified, then it will return all children + * that match that name or path. The path is a series of elements and + * sub-elements, separated by slashes. * * @webref xml:method * @webBrief Returns an array containing all child elements @@ -444,7 +450,9 @@ public class XML implements Serializable { /** - * Quick accessor for an element at a particular index. + * Returns the first of the element's children that matches the name + * parameter. The name or path is a series of elements and sub-elements, + * separated by slashes. * * @webref xml:method * @webBrief Returns the child element with the specified index value or path @@ -562,12 +570,16 @@ public class XML implements Serializable { } - /** - * Appends a new child to the element - * - * @webref xml:method - * @webBrief Appends a new child to the element - */ + /** + * Appends a new child to the element. The child can be specified with either a + * String, which will be used as the new tag's name, or as a reference to an + * existing XML object.
+ *
+ * A reference to the newly created child is returned as an XML object. + * + * @webref xml:method + * @webBrief Appends a new child to the element + */ public XML addChild(String tag) { Document document = node.getOwnerDocument(); Node newChild = document.createElement(tag); @@ -593,12 +605,14 @@ public class XML implements Serializable { } - /** - * Removes the specified child - * - * @webref xml:method - * @webBrief Removes the specified child - */ + /** + * Removes the specified element. First use getChild() to get a reference + * to the desired element. Then pass that reference to removeChild() to + * delete it. + * + * @webref xml:method + * @webBrief Removes the specified child + */ public void removeChild(XML kid) { node.removeChild(kid.node); children = null; // TODO not efficient @@ -681,7 +695,7 @@ public class XML implements Serializable { /** - * Returns the number of attributes. + * Counts the specified element's number of attributes, returned as an int. * * @webref xml:method * @webBrief Counts the specified element's number of attributes @@ -692,7 +706,7 @@ public class XML implements Serializable { /** - * Get a list of the names for all of the attributes for this node. + * Gets all of the specified element's attributes, and returns them as an array of Strings. * * @webref xml:method * @webBrief Returns a list of names of all attributes as an array @@ -707,7 +721,8 @@ public class XML implements Serializable { } /** - * Returns whether an attribute exists. + * Checks whether or not an element has the specified attribute. The attribute + * must be specified as a String, and a boolean is returned. * * @webref xml:method * @webBrief Checks whether or not an element has the specified attribute @@ -742,7 +757,10 @@ public class XML implements Serializable { /** - * Gets the content of an attribute as a String + * Returns an attribute value of the element as a String. If the defaultValue + * parameter is specified and the attribute doesn't exist, then defaultValue + * is returned. If no defaultValue is specified and the attribute doesn't + * exist, null is returned. * * @webref xml:method * @webBrief Gets the content of an attribute as a String @@ -765,7 +783,8 @@ public class XML implements Serializable { /** - * Sets the content of an attribute as a String + * Sets the content of an element's attribute as a String. The first String + * specifies the attribute name, while the second specifies the new content. * * @webref xml:method * @webBrief Sets the content of an attribute as a String @@ -776,7 +795,10 @@ public class XML implements Serializable { /** - * Gets the content of an attribute as an int + * Returns an attribute value of the element as an int. If the defaultValue + * parameter is specified and the attribute doesn't exist, then defaultValue + * is returned. If no defaultValue is specified and the attribute doesn't + * exist, the value 0 is returned. * * @webref xml:method * @webBrief Gets the content of an attribute as an int @@ -787,7 +809,8 @@ public class XML implements Serializable { /** - * Sets the content of an attribute as an int + * Sets the content of an element's attribute as an int. A String specifies + * the attribute name, while the int specifies the new content. * * @webref xml:method * @webBrief Sets the content of an attribute as an int @@ -834,12 +857,15 @@ public class XML implements Serializable { } - /** - * Returns the value of an attribute, or zero if not present. - * - * @webref xml:method - * @webBrief Gets the content of an attribute as a float - */ + /** + * Returns an attribute value of the element as a float. If the + * defaultValue parameter is specified and the attribute doesn't exist, + * then defaultValue is returned. If no defaultValue is specified + * and the attribute doesn't exist, the value 0.0 is returned. + * + * @webref xml:method + * @webBrief Gets the content of an attribute as a float + */ public float getFloat(String name) { return getFloat(name, 0); } @@ -859,7 +885,8 @@ public class XML implements Serializable { /** - * Sets the content of an attribute as a float + * Sets the content of an element's attribute as a float. A String specifies + * the attribute name, while the float specifies the new content. * * @webref xml:method * @webBrief Sets the content of an attribute as a float @@ -893,10 +920,8 @@ public class XML implements Serializable { /** - * Return the #PCDATA content of the element. If the element has a - * combination of #PCDATA content and child elements, the #PCDATA - * sections can be retrieved as unnamed child objects. In this case, - * this method returns null. + * Returns the content of an element. If there is no such content, + * null is returned. * * @webref xml:method * @webBrief Gets the content of an element @@ -916,7 +941,8 @@ public class XML implements Serializable { /** - * Gets the content of an element as an int + * Returns the content of an element as an int. If there is no such content, + * either null or the provided default value is returned. * * @webref xml:method * @webBrief Gets the content of an element as an int @@ -938,7 +964,8 @@ public class XML implements Serializable { /** - * Gets the content of an element as a float + * Returns the content of an element as a float. If there is no such content, + * either null or the provided default value is returned. * * @webref xml:method * @webBrief Gets the content of an element as a float @@ -992,7 +1019,7 @@ public class XML implements Serializable { /** - * Sets the content of an element + * Sets the element's content, which is specified as a String. * * @webref xml:method * @webBrief Sets the content of an element @@ -1022,15 +1049,25 @@ public class XML implements Serializable { } - /** - * Format this XML data as a String. - * - * @webref xml:method - * @webBrief Formats XML data as a String - * @param indent -1 for a single line (and no declaration), >= 0 for indents and newlines - * @return the content - * @see XML#toString() - */ + /** + * Takes an XML object and converts it to a String, formatting its content as + * specified with the indent parameter.
+ *
+ * If indent is set to -1, then the String is returned with no line breaks, no + * indentation, and no XML declaration.
+ *
+ * If indent is set to 0 or greater, then the String is returned with line + * breaks, and the specified number of spaces as indent values. Meaning, there + * will be no indentation if 0 is specified, or each indent will be replaced + * with the corresponding number of spaces: 1, 2, 3, and so on. + * + * @webref xml:method + * @webBrief Formats XML data as a String + * @param indent -1 for a single line (and no declaration), >= 0 for indents and + * newlines + * @return the content + * @see XML#toString() + */ public String format(int indent) { try { // entities = doctype.getEntities() @@ -1166,16 +1203,17 @@ public class XML implements Serializable { } - /** - * Return the XML document formatted with two spaces for indents. - * Chosen to do this since it's the most common case (e.g. with println()). - * Same as format(2). Use the format() function for more options. - * - * @webref xml:method - * @webBrief Gets XML data as a String using default formatting - * @return the content - * @see XML#format(int) - */ + /** + * Takes an XML object and converts it to a String, using default formatting + * rules (includes an XML declaration, line breaks, and two spaces for indents). + * These are the same formatting rules used by println() when printing an + * XML object. This method produces the same results as using format(2). + * + * @webref xml:method + * @webBrief Gets XML data as a String using default formatting + * @return the content + * @see XML#format(int) + */ @Override public String toString() { //return format(2); diff --git a/java/libraries/io/src/processing/io/I2C.java b/java/libraries/io/src/processing/io/I2C.java index 2e5dedb4e..c97eefe58 100644 --- a/java/libraries/io/src/processing/io/I2C.java +++ b/java/libraries/io/src/processing/io/I2C.java @@ -30,7 +30,31 @@ import java.util.Arrays; /** - * @webref + * Opens an I2C interface as master.
+ *
+ * I2C is a serial bus, commonly used to attach peripheral ICs (Integrated + * Circuits) to processors and microcontrollers. It uses two pins, SDA (for + * data) and SDL (for the clock signal). Multiple "slave" devices can be + * connected to the same bus, as long as they are responding to different + * addresses (see below).
+ *
+ * The I2C "master" device initiates a transmission, which includes sending the + * address of the desired "slave" device. I2C addresses consist of 7 bits plus + * one bit that indicates whether the device is being read from or written to. + * Some datasheets list the address in an 8 bit form (7 address bits + R/W bit), + * while others provide the address in a 7 bit form, with the address in the + * lower 7 bits.
+ *
+ * This library expects addresses in their 7 bit form, similar to Arduino's Wire + * library, and what is being output by the i2cdetect utility on Linux. If the + * address provided in a datasheet is greater than 127 (hex 0x7f) or there are + * separate addresses for read and write operations listed, which vary exactly + * by one, then you want to shift the this number by one bit to the right before + * passing it as an argument to + * beginTransmission(). + * + * @webref + * @webBrief Opens an I2C interface as master */ public class I2C { @@ -62,13 +86,22 @@ public class I2C { } - /** - * Begins a transmission to an attached device - * @see write - * @see read - * @see endTransmission - * @webref - */ + /** + * Begins a transmission to an attached device.
+ *
+ * This function expects the address in the lower 7 bits, the same way as in + * Arduino's Wire library, and as shown in the output of the i2cdetect tool. If + * the address provided in a datasheet is greater than 127 (hex 0x7f) or there + * are separate addresses for read and write operations listed, which vary + * exactly by one, then you want to shift the this number by one bit to the + * right before passing it as an argument to this function. + * + * @see write + * @see read + * @see endTransmission + * @webref + * @webBrief Begins a transmission to an attached device + */ public void beginTransmission(int slave) { // addresses 120 (0x78) to 127 are additionally reserved if (0x78 <= slave) { @@ -81,10 +114,18 @@ public class I2C { } - /** - * Closes the I2C device - * @webref - */ + /** + * Closes the I2C device
+ *
+ * It is normally not necessary to explicitly close I2C interfaces, as they are + * closed automatically by the operating system when the sketch exits.
+ *
+ * Note: It is possible to have two or more object using the same interface at a + * time. + * + * @webref + * @webBrief Closes the I2C device. + */ public void close() { if (NativeInterface.isSimulated()) { return; @@ -104,12 +145,18 @@ public class I2C { } - /** - * Ends the current transmissions - * @see beginTransmission - * @see write - * @webref - */ + /** + * Ends the current transmissions
+ *
+ * This executes any queued writes. Read() + * implicitly ends the current transmission as well, hence calling + * endTransmission() afterwards is not necessary. + * + * @see beginTransmission + * @see write + * @webref + * @webBrief Ends the current transmissions. + */ public void endTransmission() { if (!transmitting) { // silently ignore this case @@ -137,6 +184,7 @@ public class I2C { * Lists all available I2C interfaces * @return String array * @webref + * @webBrief Lists all available I2C interfaces */ public static String[] list() { if (NativeInterface.isSimulated()) { @@ -161,15 +209,22 @@ public class I2C { } - /** - * Reads bytes from the attached device - * @param len number of bytes to read - * @return bytes read from device - * @see beginTransmission - * @see write - * @see endTransmission - * @webref - */ + /** + * Read bytes from the attached device
+ *
+ * You must call beginTransmission() before calling this function. This function + * also ends the current transmission and sends any data that was queued using + * write() before. It is not necessary to call + * endTransmission() after read(). + * + * @param len number of bytes to read + * @return bytes read from device + * @see beginTransmission + * @see write + * @see endTransmission + * @webref + * @webBrief Read bytes from the attached device. + */ public byte[] read(int len) { if (!transmitting) { throw new RuntimeException("beginTransmisson has not been called"); @@ -195,14 +250,19 @@ public class I2C { } - /** - * Adds bytes to be written to the device - * @param out bytes to be written - * @see beginTransmission - * @see read - * @see endTransmission - * @webref - */ + /** + * Add bytes to be written to the device
+ *
+ * You must call beginTransmission() before calling this function. The actual + * writing takes part when read() or endTransmission() is being called. + * + * @param out bytes to be written + * @see beginTransmission + * @see read + * @see endTransmission + * @webref + * @webBrief Add bytes to be written to the device. + */ public void write(byte[] out) { if (!transmitting) { throw new RuntimeException("beginTransmisson has not been called"); diff --git a/java/libraries/io/src/processing/io/LED.java b/java/libraries/io/src/processing/io/LED.java index 32925e6ea..ca436ac83 100644 --- a/java/libraries/io/src/processing/io/LED.java +++ b/java/libraries/io/src/processing/io/LED.java @@ -33,7 +33,19 @@ import java.util.Arrays; /** - * @webref + * Opens a LED device.
+ *
+ * This class can control your computer's build-in LEDs, such as the ones + * commonly used to indicate the power status and disk activity.
+ *
+ * Your operating system might not be set up to allow regular users to do this + * kind of modification. If this is the case you should install a so-called + * udev rule that relaxes the permissions for the files in + * /sys/class/leds. You can also try running Processing as root user using + * "sudo", but this is generally not recommended. + * + * @webref + * @webBrief Opens a LED device */ public class LED { @@ -47,7 +59,7 @@ public class LED { * Opens a LED device * @param dev device name * @see list - * @webref + * @webref Opens a LED device */ public LED(String dev) { NativeInterface.loadLibrary(); @@ -107,6 +119,7 @@ public class LED { * Sets the brightness * @param bright 0.0 (off) to 1.0 (maximum) * @webref + * @webBrief Sets the brightness */ public void brightness(float bright) { if (bright < 0.0 || 1.0 < bright) { @@ -126,10 +139,15 @@ public class LED { } - /** - * Restores the previous state - * @webref - */ + /** + * Restores the previous state
+ *
+ * Without calling this function the LED will remain in the current state even + * after the sketch has been closed. + * + * @webref + * @webBrief Restores the previous state + */ public void close() { if (NativeInterface.isSimulated()) { return; @@ -154,6 +172,7 @@ public class LED { * Lists all available LED devices * @return String array * @webref + * @webBrief Lists all available LED devices */ public static String[] list() { if (NativeInterface.isSimulated()) { diff --git a/java/libraries/io/src/processing/io/PWM.java b/java/libraries/io/src/processing/io/PWM.java index c33c9107c..0762add55 100644 --- a/java/libraries/io/src/processing/io/PWM.java +++ b/java/libraries/io/src/processing/io/PWM.java @@ -33,7 +33,10 @@ import java.util.Arrays; /** + * Opens a PWM channel + * * @webref + * @webBrief Opens a PWM channel */ public class PWM { @@ -45,7 +48,7 @@ public class PWM { * Opens a PWM channel * @param channel PWM channel * @see list - * @webref + * @webref Opens a PWM channel */ public PWM(String channel) { NativeInterface.loadLibrary(); @@ -90,7 +93,9 @@ public class PWM { /** * Disables the PWM output + * * @webref + * @webBrief Disables the PWM output */ public void clear() { if (NativeInterface.isSimulated()) { @@ -105,10 +110,15 @@ public class PWM { } - /** - * Gives ownership of a channel back to the operating system - * @webref - */ + /** + * Gives ownership of a channel back to the operating system
+ *
+ * Without calling this function the channel will remain in the current state + * even after the sketch has been closed. + * + * @webref + * @webBrief Gives ownership of a channel back to the operating system + */ public void close() { if (NativeInterface.isSimulated()) { return; @@ -134,6 +144,7 @@ public class PWM { * Lists all available PWM channels * @return String array * @webref + * @webBrief Lists all available PWM channels */ public static String[] list() { if (NativeInterface.isSimulated()) { @@ -164,12 +175,16 @@ public class PWM { } - /** - * Enables the PWM output - * @param period cycle period in Hz - * @param duty duty cycle, 0.0 (always off) to 1.0 (always on) - * @webref - */ + /** + * Enables the PWM output
+ *
+ * When no period is specified, a default 1 kHz (1000 Hz) is used. + * + * @param period cycle period in Hz + * @param duty duty cycle, 0.0 (always off) to 1.0 (always on) + * @webref + * @webBrief Enables the PWM output + */ public void set(int period, float duty) { if (NativeInterface.isSimulated()) { return; @@ -206,7 +221,7 @@ public class PWM { /** * Enables the PWM output with a preset period of 1 kHz - * @webref + * @nowebref */ public void set(float duty) { set(1000, duty); diff --git a/java/libraries/io/src/processing/io/SPI.java b/java/libraries/io/src/processing/io/SPI.java index b1a8369ea..2bbb2583b 100644 --- a/java/libraries/io/src/processing/io/SPI.java +++ b/java/libraries/io/src/processing/io/SPI.java @@ -32,7 +32,29 @@ import java.util.Map; /** - * @webref + * Opens an SPI interface as master
+ *
+ * Serial Peripheral Interface (SPI) is a serial bus, commonly used to + * communicate with sensors and memory devices. It uses four pins: MOSI (Master + * Out Slave In), MISO (Master In Slave Out), and SCLK (clock signal) - those + * three are shared among all devices on the bus - as well as one or more SS + * (Slave Select) pins, that are used for the master to signal to the slave + * device that it is the desired respondent for the transmission.
+ *
+ * The "master" device initiates a transfer by pulling the SS pin of the "slave" + * low, and begins outputting a clock signal. In SPI, both the "master" as well + * as the "slave" device output data at the same time. It is hence not possible + * to read data without writing some (even if it means outputting zeros or other + * dummy data).
+ *
+ * There are multiple possible configuration settings for SPI, see + * settings() for details.
+ *
+ * This library supports multiple SPI objects making use of the same SPI + * interface. + * + * @webref + * @webBrief Opens an SPI interface as master */ public class SPI { @@ -74,6 +96,7 @@ public class SPI { * @param dev device name * @see list * @webref + * @webBrief Opens an SPI interface as master */ public SPI(String dev) { NativeInterface.loadLibrary(); @@ -90,10 +113,18 @@ public class SPI { } - /** - * Closes the SPI interface - * @webref - */ + /** + * Closes the SPI interface
+ *
+ * It is normally not necessary to explicitly close SPI interfaces, as they are + * closed automatically by the operating system when the sketch exits.
+ *
+ * Note: It is possible to have two or more objects using the same interface at + * a time. + * + * @webref + * @webBrief Closes the SPI interface + */ public void close() { if (NativeInterface.isSimulated()) { return; @@ -117,6 +148,7 @@ public class SPI { * Lists all available SPI interfaces * @return String array * @webref + * @webBrief Lists all available SPI interfaces */ public static String[] list() { if (NativeInterface.isSimulated()) { @@ -141,13 +173,22 @@ public class SPI { } - /** - * Configures the SPI interface - * @param maxSpeed maximum transmission rate in Hz, 500000 (500 kHz) is a resonable default - * @param dataOrder whether data is send with the first- or least-significant bit first (SPI.MSBFIRST or SPI.LSBFIRST, the former is more common) - * @param mode SPI.MODE0 to SPI.MODE3 - * @webref - */ + /** + * Configures the SPI interface
+ *
+ * The default setting is: 500000, SPI.MSBFIRST, SPI.MODE0 + * + * @param maxSpeed maximum transmission rate in Hz, 500000 (500 kHz) is a + * resonable default + * @param dataOrder whether data is send with the first- or least-significant + * bit first (SPI.MSBFIRST or SPI.LSBFIRST, the former is more + * common) + * @param mode SPI.MODE0 + * to SPI.MODE3 + * @webref + * @webBrief Configures the SPI interface + */ public void settings(int maxSpeed, int dataOrder, int mode) { this.maxSpeed = maxSpeed; this.dataOrder = dataOrder; @@ -155,12 +196,17 @@ public class SPI { } - /** - * Transfers data over the SPI bus - * @param out bytes to send - * @return bytes read in (array is the same length as out) - * @webref - */ + /** + * Transfers data over the SPI bus
+ *
+ * With SPI, data is simultaneously being exchanged between the master device + * and the slave device. For every byte that is being sent out, there's also one + * byte being read in. + * + * @param out bytes to send + * @return bytes read in (array is the same length as out) + * @webref Transfers data over the SPI bus + */ public byte[] transfer(byte[] out) { if (NativeInterface.isSimulated()) { return new byte[out.length]; diff --git a/java/libraries/io/src/processing/io/SoftwareServo.java b/java/libraries/io/src/processing/io/SoftwareServo.java index db5cbdcbe..a0ff55876 100644 --- a/java/libraries/io/src/processing/io/SoftwareServo.java +++ b/java/libraries/io/src/processing/io/SoftwareServo.java @@ -26,7 +26,17 @@ import processing.core.*; /** - * @webref + * Opens an RC servo motor connected to a GPIO pin
+ *
+ * This library uses timers to control RC servo motors by means of pulse width + * modulation (PWM). While not as accurate as dedicated PWM hardware, it has + * shown to be sufficient for many applications.
+ *
+ * Connect the signal wire (typically colored yellow) to any available GPIO pin + * and control the servo's angle as shown in the example sketch. + * + * @webref + * @webBrief Opens an RC servo motor connected to a GPIO pin */ public class SoftwareServo { @@ -45,6 +55,7 @@ public class SoftwareServo { * Opens a servo motor * @param parent typically use "this" * @webref + * @webBrief Opens a servo motor */ public SoftwareServo(PApplet parent) { NativeInterface.loadLibrary(); @@ -54,6 +65,7 @@ public class SoftwareServo { /** * Closes a servo motor * @webref + * @webBrief Closes a servo motor */ public void close() { detach(); @@ -69,11 +81,20 @@ public class SoftwareServo { } - /** - * Attaches a servo motor to a GPIO pin - * @param pin GPIO pin - * @webref - */ + /** + * Attaches a servo motor to a GPIO pin
+ *
+ * You must call this function before calling write(). Note that the servo motor + * will only be instructed to move after the first time write() is called.
+ *
+ * The optional parameters minPulse and maxPulse control the minimum and maximum + * pulse width durations. The default values, identical to those of Arduino's + * Servo class, should be compatible with most servo motors. + * + * @param pin GPIO pin + * @webref + * @webBrief Attaches a servo motor to a GPIO pin + */ public void attach(int pin) { detach(); this.pin = pin; @@ -96,11 +117,19 @@ public class SoftwareServo { } - /** - * Moves a servo motor to a given orientation - * @param angle angle in degrees (controls speed and direction on continuous-rotation servos) - * @webref - */ + /** + * Moves a servo motor to a given orientation
+ *
+ * If you are using this class in combination with a continuous rotation servo, + * different angles will result in the servo rotating forward or backward at + * different speeds. For regular servo motors, this will instruct the servo to + * rotate to and hold a specific angle. + * + * @param angle angle in degrees (controls speed and direction on + * continuous-rotation servos) + * @webref + * @webBrief Moves a servo motor to a given orientation + */ public void write(float angle) { if (attached() == false) { System.err.println("You need to call attach(pin) before write(angle)."); @@ -137,16 +166,22 @@ public class SoftwareServo { * Returns whether a servo motor is attached to a pin * @return true if attached, false is not * @webref + * @webBrief Returns whether a servo motor is attached to a pin */ public boolean attached() { return (pin != -1); } - /** - * Detatches a servo motor from a GPIO pin - * @webref - */ + /** + * Detatches a servo motor from a GPIO pin
+ *
+ * Calling this method will stop the servo from moving or trying to hold the + * current orientation. + * + * @webref + * @webBrief Detatches a servo motor from a GPIO pin + */ public void detach() { if (0 <= handle) { // stop thread diff --git a/java/libraries/net/src/processing/net/Client.java b/java/libraries/net/src/processing/net/Client.java index 983cfc5bf..023988bbf 100644 --- a/java/libraries/net/src/processing/net/Client.java +++ b/java/libraries/net/src/processing/net/Client.java @@ -303,11 +303,11 @@ public class Client implements Runnable { /** * - * Returns true if this client is still active and hasn't run + * Returns true if this client is still active and hasn't run * into any trouble. * * @webref client:client - * @webBrief Returns true if this client is still active + * @webBrief Returns true if this client is still active * @usage application */ public boolean active() { @@ -389,8 +389,8 @@ public class Client implements Runnable { /** * - * Returns the next byte in the buffer as a char. Returns -1 or 0xffff if - * nothing is there. + * Returns the next byte in the buffer as a char. Returns -1 or + * 0xffff if nothing is there. * * @webref client:client * @usage application @@ -422,7 +422,7 @@ public class Client implements Runnable { * * @webref client:client * @usage application - * @webBrief Reads everything in the buffer + * @webBrief Reads a group of bytes from the buffer. */ public byte[] readBytes() { synchronized (bufferLock) { @@ -638,11 +638,13 @@ public class Client implements Runnable { /** * - * Writes data to a server specified when constructing the client. + * Writes data to a server specified when constructing the client, or writes + * data to the specific client obtained from the Server available() + * method. * * @webref client:client * @usage application - * @webBrief Writes bytes, chars, ints, bytes[], Strings + * @webBrief Writes bytes, chars, ints, bytes[], Strings * @param data data to write */ public void write(int data) { // will also cover char diff --git a/java/libraries/net/src/processing/net/Server.java b/java/libraries/net/src/processing/net/Server.java index b10f03d4d..81f29a0a0 100644 --- a/java/libraries/net/src/processing/net/Server.java +++ b/java/libraries/net/src/processing/net/Server.java @@ -184,7 +184,7 @@ public class Server implements Runnable { /** * - * Returns true if this server is still active and hasn't run + * Returns true if this server is still active and hasn't run * into any trouble. * * @webref server:server diff --git a/java/libraries/serial/src/processing/serial/Serial.java b/java/libraries/serial/src/processing/serial/Serial.java index fffd075cc..e2ff09437 100644 --- a/java/libraries/serial/src/processing/serial/Serial.java +++ b/java/libraries/serial/src/processing/serial/Serial.java @@ -724,7 +724,6 @@ public class Serial implements SerialPortEventListener { /** * Writes bytes, chars, ints, bytes[], Strings to the serial port * - * @generate Serial_write.xml *

Advanced

* Write a String to the output. Note that this doesn't account * for Unicode (two bytes per char), nor will it send UTF8