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