Package processing.core

Class PGraphics

java.lang.Object

processing.core.PImage

processing.core.PGraphics

All Implemented Interfaces:

Cloneable, PConstants

Direct Known Subclasses:

PGraphicsJava2D, PGraphicsOpenGL

public class PGraphics
extends PImage
implements PConstants

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, but except for 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 coordinates 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.

See Also:

• PApplet.createGraphics(int, int, String)

Usage:

Web & Application

Field Summary

Fields

Modifier and Type	Field	Description
static final int	A
static final int	AB
static final int	AG
float	ambientB
int	ambientColor
float	ambientG
float	ambientR
static final int	AR
static final int	B
int	backgroundColor	Last background color that was set, zero if an image
static final int	BEEN_LIT
int	bezierDetail
int	colorMode	The current colorMode
float	colorModeA	Max value for alpha set by colorMode
float	colorModeX	Max value for red (or hue) set by colorMode
float	colorModeY	Max value for green (or saturation) set by colorMode
float	colorModeZ	Max value for blue (or value) set by colorMode
int	curveDetail
float	curveTightness
static final int	DA
static final int	DB
static final int	DEFAULT_VERTICES
static final int	DG
static final int	DR
static final int	EB
boolean	edge
static final int	EDGE
static final int	EG
int	ellipseMode	The current ellipse mode (read-only)
float	emissiveB
int	emissiveColor
float	emissiveG
float	emissiveR
static final int	ER
boolean	fill	true if fill() is enabled, (read-only)
int	fillColor	fill that was last set (read-only)
static final int	G
static final int	HAS_NORMAL
Image	image	Java AWT Image object associated with this renderer.
int	imageMode	The current image alignment (read-only)
float	normalX	Current normal vector.
float	normalY	Current normal vector.
float	normalZ	Current normal vector.
static final int	NX
static final int	NY
static final int	NZ
int	pixelCount	width * height (useful for many calculations)
static final int	R
int	rectMode	The current rect mode (read-only)
static final int	SA
static final int	SB
boolean	setAmbient
static final int	SG
int	shapeMode	The current shape alignment mode (read-only)
static final int	SHINE
float	shininess
int	smooth	the anti-aliasing level for renderers that support it
static final int	SPB
float	specularB
int	specularColor
float	specularG
float	specularR
static final int	SPG
int	sphereDetailU
int	sphereDetailV
static final int	SPR
static final int	SR	stroke argb values
boolean	stroke	true if stroke() is enabled, (read-only)
int	strokeCap	Set by strokeCap() (read-only).
int	strokeColor	stroke that was last set (read-only)
int	strokeJoin	Set by strokeJoin() (read-only).
float	strokeWeight	Last value set by strokeWeight() (read-only).
static final int	SW	stroke weight
int	textAlign	The current text align (read-only)
int	textAlignY	The current vertical text alignment (read-only)
PFont	textFont	The current text font (read-only)
float	textLeading	The current text leading (read-only)
int	textMode	The current text mode (read-only)
float	textSize	The current text size (read-only)
PImage	textureImage	Current image being used as a texture
int	textureMode	Sets whether texture coordinates passed to vertex() calls will be based on coordinates that are based on the IMAGE or NORMALIZED.
float	textureU	Current horizontal coordinate for texture, will always be between 0 and 1, even if using textureMode(IMAGE).
float	textureV	Current vertical coordinate for texture, see above.
boolean	tint	True if tint() is enabled (read-only).
int	tintColor	tint that was last set (read-only)
static final int	TX
static final int	TY
static final int	TZ
static final int	U
static final int	V
static final int	VERTEX_FIELD_COUNT
static final int	VW
static final int	VX
static final int	VY
static final int	VZ

Fields inherited from class processing.core.PImage

ALPHA_MASK, BLUE_MASK, format, GREEN_MASK, height, loaded, parent, pixelDensity, pixelHeight, pixels, pixelWidth, RED_MASK, width

Fields inherited from interface processing.core.PConstants

ADD, ALPHA, ALT, AMBIENT, ARC, ARGB, ARROW, BACKSPACE, BASELINE, BEVEL, BEZIER_VERTEX, BLEND, BLUR, BOTTOM, BOX, BREAK, BURN, CENTER, CHATTER, CHORD, CLAMP, CLOSE, CODED, COMPLAINT, CONTROL, CORNER, CORNERS, CROSS, CURVE_VERTEX, CUSTOM, DARKEST, DEG_TO_RAD, DELETE, DIAMETER, DIFFERENCE, DILATE, DIRECTIONAL, DISABLE_ASYNC_SAVEFRAME, DISABLE_BUFFER_READING, DISABLE_DEPTH_MASK, DISABLE_DEPTH_SORT, DISABLE_DEPTH_TEST, DISABLE_KEY_REPEAT, DISABLE_NATIVE_FONTS, DISABLE_OPENGL_ERRORS, DISABLE_OPTIMIZED_STROKE, DISABLE_STROKE_PERSPECTIVE, DISABLE_STROKE_PURE, DISABLE_TEXTURE_MIPMAPS, DODGE, DOWN, DXF, ELLIPSE, ENABLE_ASYNC_SAVEFRAME, ENABLE_BUFFER_READING, ENABLE_DEPTH_MASK, ENABLE_DEPTH_SORT, ENABLE_DEPTH_TEST, ENABLE_KEY_REPEAT, ENABLE_NATIVE_FONTS, ENABLE_OPENGL_ERRORS, ENABLE_OPTIMIZED_STROKE, ENABLE_STROKE_PERSPECTIVE, ENABLE_STROKE_PURE, ENABLE_TEXTURE_MIPMAPS, ENTER, EPSILON, ERODE, ESC, EXCLUSION, FX2D, GIF, GRAY, GROUP, HALF_PI, HAND, HARD_LIGHT, HINT_COUNT, HSB, IMAGE, INVERT, JAVA2D, JPEG, LANDSCAPE, LEFT, LIGHTEST, LINE, LINE_LOOP, LINE_STRIP, LINES, LINUX, MACOS, MACOSX, MAX_FLOAT, MAX_INT, MIN_FLOAT, MIN_INT, MITER, MODEL, MODELVIEW, MOVE, MULTIPLY, NORMAL, OPAQUE, OPEN, OPENGL, ORTHOGRAPHIC, OTHER, OVERLAY, P2D, P3D, PATH, PDF, PERSPECTIVE, PI, PIE, platformNames, POINT, POINTS, POLYGON, PORTRAIT, POSTERIZE, PROBLEM, PROJECT, PROJECTION, QUAD, QUAD_BEZIER_VERTEX, QUAD_STRIP, QUADRATIC_VERTEX, QUADS, QUARTER_PI, RAD_TO_DEG, RADIUS, RECT, REPEAT, REPLACE, RETURN, RGB, RIGHT, ROUND, SCREEN, SHAPE, SHIFT, SOFT_LIGHT, SPAN, SPHERE, SPOT, SQUARE, SUBTRACT, SVG, TAB, TARGA, TAU, TEXT, THIRD_PI, THRESHOLD, TIFF, TOP, TRIANGLE, TRIANGLE_FAN, TRIANGLE_STRIP, TRIANGLES, TWO_PI, UP, VERTEX, WAIT, WHITESPACE, WINDOWS, X, Y, Z

Constructor Summary

Constructors

Constructor	Description
PGraphics()

Method Summary

Modifier and Type	Method	Description
final float	alpha(int rgb)	Extracts the alpha value from a color.
void	ambient(float gray)
void	ambient(float v1, float v2, float v3)
void	ambient(int rgb)	Sets the ambient reflectance for shapes drawn to the screen.
void	ambientLight(float v1, float v2, float v3)	Adds an ambient light.
void	ambientLight(float v1, float v2, float v3, float x, float y, float z)
void	applyMatrix(float n00, float n01, float n02, float n10, float n11, float n12)
void	applyMatrix(float n00, float n01, float n02, float n03, float n10, float n11, float n12, float n13, float n20, float n21, float n22, float n23, float n30, float n31, float n32, float n33)
void	applyMatrix(PMatrix source)	Multiplies the current matrix by the one specified through the parameters.
void	applyMatrix(PMatrix2D source)
void	applyMatrix(PMatrix3D source)
void	arc(float a, float b, float c, float d, float start, float stop)	Draws an arc to the screen.
void	arc(float a, float b, float c, float d, float start, float stop, int mode)
void	attrib(String name, boolean... values)
void	attrib(String name, float... values)
void	attrib(String name, int... values)
void	attribColor(String name, int color)
void	attribNormal(String name, float nx, float ny, float nz)
void	attribPosition(String name, float x, float y, float z)
void	background(float gray)
void	background(float gray, float alpha)
void	background(float v1, float v2, float v3)
void	background(float v1, float v2, float v3, float alpha)
void	background(int rgb)	The background() function sets the color used for the background of the Processing window.
void	background(int rgb, float alpha)
void	background(PImage image)	Takes an RGB or ARGB image and sets it as the background.
void	beginCamera()	The beginCamera() and endCamera() functions enable advanced customization of the camera space.
void	beginContour()	Use the beginContour() and endContour() function to create negative shapes within shapes such as the center of the letter "O".
void	beginDraw()	Sets the default properties for a PGraphics object.
PGL	beginPGL()
void	beginRaw(PGraphics rawGraphics)	Record individual lines and triangles by echoing them to another renderer.
void	beginShape()	Start a new shape of type POLYGON
void	beginShape(int kind)	Using the beginShape() and endShape() functions allow creating more complex forms.
void	bezier(float x1, float y1, float x2, float y2, float x3, float y3, float x4, float y4)
void	bezier(float x1, float y1, float z1, float x2, float y2, float z2, float x3, float y3, float z3, float x4, float y4, float z4)	Draws a Bézier curve on the screen.
void	bezierDetail(int detail)	Sets the resolution at which Bézier curves display.
float	bezierPoint(float a, float b, float c, float d, float t)	Evaluates the Bezier at point t for points a, b, c, d.
float	bezierTangent(float a, float b, float c, float d, float t)	Calculates the tangent of a point on a Bézier curve.
void	bezierVertex(float x2, float y2, float x3, float y3, float x4, float y4)
void	bezierVertex(float x2, float y2, float z2, float x3, float y3, float z3, float x4, float y4, float z4)	Specifies vertex coordinates for Bézier curves.
void	blendMode(int mode)	Blends the pixels in the display window according to a defined mode.
final float	blue(int rgb)	Extracts the blue value from a color, scaled to match current colorMode().
void	box(float size)	A box is an extruded rectangle.
void	box(float w, float h, float d)
final float	brightness(int rgb)	Extracts the brightness value from a color.
void	camera()	Sets the position of the camera through setting the eye position, the center of the scene, and which axis is facing upward.
void	camera(float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ)
void	circle(float x, float y, float extent)	Draws a circle to the screen.
void	clear()	Clears the pixels within a buffer.
void	clip(float a, float b, float c, float d)	Limits the rendering to the boundaries of a rectangle defined by the parameters.
final int	color(float gray)
final int	color(float gray, float alpha)
final int	color(float v1, float v2, float v3)
final int	color(float v1, float v2, float v3, float a)
final int	color(int c)
final int	color(int c, float alpha)
final int	color(int c, int alpha)
final int	color(int v1, int v2, int v3)
final int	color(int v1, int v2, int v3, int a)
void	colorMode(int mode)	Changes the way Processing interprets color data.
void	colorMode(int mode, float max)
void	colorMode(int mode, float max1, float max2, float max3)
void	colorMode(int mode, float max1, float max2, float max3, float maxA)
PShape	createShape()	The createShape() function is used to define a new shape.
PShape	createShape(int type)
PShape	createShape(int kind, float... p)
PSurface	createSurface()
void	curve(float x1, float y1, float x2, float y2, float x3, float y3, float x4, float y4)	Draws a curved line on the screen.
void	curve(float x1, float y1, float z1, float x2, float y2, float z2, float x3, float y3, float z3, float x4, float y4, float z4)
void	curveDetail(int detail)	Sets the resolution at which curves display.
float	curvePoint(float a, float b, float c, float d, float t)	Evaluates the curve at point t for points a, b, c, d.
float	curveTangent(float a, float b, float c, float d, float t)	Calculates the tangent of a point on a curve.
void	curveTightness(float tightness)	Modifies the quality of forms created with curve() and curveVertex().
void	curveVertex(float x, float y)	Specifies vertex coordinates for curves.
void	curveVertex(float x, float y, float z)
void	directionalLight(float v1, float v2, float v3, float nx, float ny, float nz)	Adds a directional light.
boolean	displayable()	Return true if this renderer should be drawn to the screen.
void	dispose()	Handle any shutdown for this graphics context.
void	edge(boolean edge)	Sets whether the upcoming vertex is part of an edge.
void	ellipse(float a, float b, float c, float d)	Draws an ellipse (oval) to the screen.
void	ellipseMode(int mode)	Modifies the location from which ellipses are drawn by changing the way in which parameters given to ellipse() are interpreted. 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 shape'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.
void	emissive(float gray)	gray number specifying value between white and black
void	emissive(float v1, float v2, float v3)
void	emissive(int rgb)	Sets the emissive color of the material used for drawing shapes drawn to the screen.
void	endCamera()	The beginCamera() and endCamera() functions enable advanced customization of the camera space.
void	endContour()	Use the beginContour() and endContour() function to create negative shapes within shapes such as the center of the letter "O".
void	endDraw()	Finalizes the rendering of a PGraphics object so that it can be shown on screen.
void	endPGL()
void	endRaw()
void	endShape()
void	endShape(int mode)	The endShape() function is the companion to beginShape() and may only be called after beginShape().
void	fill(float gray)
void	fill(float gray, float alpha)
void	fill(float v1, float v2, float v3)
void	fill(float v1, float v2, float v3, float alpha)
void	fill(int rgb)	Sets the color used to fill shapes.
void	fill(int rgb, float alpha)
void	filter(PShader shader)
void	flush()
void	frustum(float left, float right, float bottom, float top, float near, float far)	Sets a perspective matrix as defined by the parameters. A frustum is a geometric form: a pyramid with its top cut off.
Object	getCache(PImage image)	Get cache storage data for the specified renderer.
PMatrix	getMatrix()
PMatrix2D	getMatrix(PMatrix2D target)	Copy the current transformation matrix into the specified target.
PMatrix3D	getMatrix(PMatrix3D target)	Copy the current transformation matrix into the specified target.
PGraphics	getRaw()
PStyle	getStyle()
PStyle	getStyle(PStyle s)
final float	green(int rgb)	Extracts the green value from a color, scaled to match current colorMode().
boolean	haveRaw()
void	hint(int which)	Set various hints and hacks for the renderer.
final float	hue(int rgb)	Extracts the hue value from a color.
void	image(PImage img, float a, float b)	The image() function draws an image to the display window.
void	image(PImage img, float a, float b, float c, float d)
void	image(PImage img, float a, float b, float c, float d, int u1, int v1, int u2, int v2)	Draw an image(), also specifying u/v coordinates.
void	imageMode(int mode)	Modifies the location from which images are drawn by changing the way in which parameters given to image() are interpreted. The default mode is imageMode(CORNER), which interprets the second and third parameters of image() as the upper-left corner of the image.
boolean	is2D()	Return true if this renderer supports 2D drawing.
boolean	is2X()
boolean	is3D()	Return true if this renderer supports 3D drawing.
boolean	isGL()	Return true if this renderer uses OpenGL.
int	lerpColor(int c1, int c2, float amt)	Calculates a color between two colors at a specific increment.
static int	lerpColor(int c1, int c2, float amt, int mode)
void	lightFalloff(float constant, float linear, float quadratic)	Sets the falloff rates for point lights, spotlights, and ambient lights.
void	lights()	Sets the default ambient light, directional light, falloff, and specular values.
void	lightSpecular(float v1, float v2, float v3)	Sets the specular color for lights.
void	line(float x1, float y1, float x2, float y2)	Draws a line (a direct path between two points) to the screen.
void	line(float x1, float y1, float z1, float x2, float y2, float z2)
PShader	loadShader(String fragFilename)	Loads a shader into the PShader object.
PShader	loadShader(String fragFilename, String vertFilename)
PShape	loadShape(String filename)	Loads geometry into a variable of type PShape.
PShape	loadShape(String filename, String options)
float	modelX(float x, float y, float z)	Returns the three-dimensional X, Y, Z position in model space.
float	modelY(float x, float y, float z)	Returns the three-dimensional X, Y, Z position in model space.
float	modelZ(float x, float y, float z)	Returns the three-dimensional X, Y, Z position in model space.
void	noClip()	Disables the clipping previously started by the clip() function.
void	noFill()	Disables filling geometry.
void	noLights()	Disable all lighting.
void	normal(float nx, float ny, float nz)	Sets the current normal vector.
void	noSmooth()
void	noStroke()	Disables drawing the stroke (outline).
void	noTexture()	Removes texture image for current shape.
void	noTint()	Removes the current fill value for displaying images and reverts to displaying images with their original hues.
void	ortho()	Sets an orthographic projection and defines a parallel clipping volume.
void	ortho(float left, float right, float bottom, float top)
void	ortho(float left, float right, float bottom, float top, float near, float far)
void	perspective()	Sets a perspective projection applying foreshortening, making distant objects appear smaller than closer ones.
void	perspective(float fovy, float aspect, float zNear, float zFar)
void	point(float x, float y)	Draws a point, a coordinate in space at the dimension of one pixel.
void	point(float x, float y, float z)
void	pointLight(float v1, float v2, float v3, float x, float y, float z)	Adds a point light.
void	pop()	The pop() function restores the previous drawing style settings and transformations after push() has changed them.
void	popMatrix()	Pops the current transformation matrix off the matrix stack.
void	popStyle()	The pushStyle() function saves the current style settings and popStyle() restores the prior settings; these functions are always used together.
void	printCamera()	Prints the current camera matrix to the Console (the text window at the bottom of Processing).
void	printMatrix()	Prints the current matrix to the Console (the text window at the bottom of Processing).
void	printProjection()	Prints the current projection matrix to the Console (the text window at the bottom of Processing).
void	push()	The push() function saves the current drawing style settings and transformations, while pop() restores these settings.
void	pushMatrix()	Pushes the current transformation matrix onto the matrix stack.
void	pushStyle()	The pushStyle() function saves the current style settings and popStyle() restores the prior settings.
void	quad(float x1, float y1, float x2, float y2, float x3, float y3, float x4, float y4)	A quad is a quadrilateral, a four sided polygon.
void	quadraticVertex(float cx, float cy, float x3, float y3)	Specifies vertex coordinates for quadratic Bézier curves.
void	quadraticVertex(float cx, float cy, float cz, float x3, float y3, float z3)
void	rect(float a, float b, float c, float d)	Draws a rectangle to the screen.
void	rect(float a, float b, float c, float d, float r)
void	rect(float a, float b, float c, float d, float tl, float tr, float br, float bl)
void	rectMode(int mode)	Modifies the location from which rectangles are drawn by changing the way in which parameters given to rect() are interpreted. 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 shape's width and height. The parameter must be written in ALL CAPS because Processing is a case-sensitive language.
final float	red(int rgb)	Extracts the red value from a color, scaled to match current colorMode().
void	removeCache(PImage image)	Remove information associated with this renderer from the cache, if any.
void	resetMatrix()	Replaces the current matrix with the identity matrix.
void	resetShader()	Restores the default shaders.
void	resetShader(int kind)
void	rotate(float angle)	Rotates a shape the amount specified by the angle parameter.
void	rotate(float angle, float x, float y, float z)	Advanced
void	rotateX(float angle)	Rotates a shape around the x-axis the amount specified by the angle parameter.
void	rotateY(float angle)	Rotates a shape around the y-axis the amount specified by the angle parameter.
void	rotateZ(float angle)	Rotates a shape around the z-axis the amount specified by the angle parameter.
final float	saturation(int rgb)	Extracts the saturation value from a color.
boolean	save(String filename)	Saves the image into a file.
void	scale(float s)	Increases or decreases the size of a shape by expanding and contracting vertices.
void	scale(float x, float y)	Advanced
void	scale(float x, float y, float z)
float	screenX(float x, float y)	Takes a three-dimensional X, Y, Z position and returns the X value for where it will appear on a (two-dimensional) screen.
float	screenX(float x, float y, float z)
float	screenY(float x, float y)	Takes a three-dimensional X, Y, Z position and returns the Y value for where it will appear on a (two-dimensional) screen.
float	screenY(float x, float y, float z)
float	screenZ(float x, float y, float z)	Takes a three-dimensional X, Y, Z position and returns the Z value for where it will appear on a (two-dimensional) screen.
void	setCache(PImage image, Object storage)	Store data of some kind for the renderer that requires extra metadata of some kind.
void	setMatrix(PMatrix source)	Set the current transformation matrix to the contents of another.
void	setMatrix(PMatrix2D source)	Set the current transformation to the contents of the specified source.
void	setMatrix(PMatrix3D source)	Set the current transformation to the contents of the specified source.
void	setParent(PApplet parent)
void	setPath(String path)
void	setPrimary(boolean primary)	Set (or unset) this as the main drawing surface.
void	setSize(int w, int h)	The final step in setting up a renderer, set its size of this renderer.
void	shader(PShader shader)	Applies the shader specified by the parameters.
void	shader(PShader shader, int kind)
void	shape(PShape shape)
void	shape(PShape shape, float x, float y)	Draws shapes to the display window.
void	shape(PShape shape, float a, float b, float c, float d)
void	shapeMode(int mode)	Modifies the location from which shapes draw.
void	shearX(float angle)	Shears a shape around the x-axis the amount specified by the angle parameter.
void	shearY(float angle)	Shears a shape around the y-axis the amount specified by the angle parameter.
void	shininess(float shine)	Sets the amount of gloss in the surface of shapes.
static void	showDepthWarning(String method)	Display a warning that the specified method is only available with 3D.
static void	showDepthWarningXYZ(String method)	Display a warning that the specified method that takes x, y, z parameters can only be used with x and y parameters in this renderer.
static void	showException(String msg)	Show a renderer-related exception that halts the program.
static void	showMethodWarning(String method)	Display a warning that the specified method is simply unavailable.
static void	showMissingWarning(String method)	Display a warning that the specified method is not implemented, meaning that it could be either a completely missing function, although other variations of it may still work properly.
static void	showVariationWarning(String str)	Error that a particular variation of a method is unavailable (even though other variations are).
static void	showWarning(String msg)	Show a renderer error, and keep track of it so that it's only shown once.
static void	showWarning(String msg, Object... args)	Version of showWarning() that takes a parsed String.
void	smooth()
void	smooth(int quality)
void	specular(float gray)	gray number specifying value between white and black
void	specular(float v1, float v2, float v3)
void	specular(int rgb)	Sets the specular color of the materials used for shapes drawn to the screen, which sets the color of highlights.
void	sphere(float r)	A sphere is a hollow ball made from tessellated triangles.
void	sphereDetail(int res)	Controls the detail used to render a sphere by adjusting the number of vertices of the sphere mesh.
void	sphereDetail(int ures, int vres)
void	spotLight(float v1, float v2, float v3, float x, float y, float z, float nx, float ny, float nz, float angle, float concentration)	Adds a spotlight.
void	square(float x, float y, float extent)	Draws a square to the screen.
void	stroke(float gray)
void	stroke(float gray, float alpha)
void	stroke(float v1, float v2, float v3)
void	stroke(float v1, float v2, float v3, float alpha)
void	stroke(int rgb)	Sets the color used to draw lines and borders around shapes.
void	stroke(int rgb, float alpha)
void	strokeCap(int cap)	Sets the style for rendering line endings.
void	strokeJoin(int join)	Sets the style of the joints which connect line segments.
void	strokeWeight(float weight)	Sets the width of the stroke used for lines, points, and the border around shapes.
void	style(PStyle s)
void	text(char[] chars, int start, int stop, float x, float y)	Advanced
void	text(char[] chars, int start, int stop, float x, float y, float z)
void	text(char c, float x, float y)	Draws text to the screen.
void	text(char c, float x, float y, float z)
void	text(float num, float x, float y)	This does a basic number formatting, to avoid the generally ugly appearance of printing floats.
void	text(float num, float x, float y, float z)
void	text(int num, float x, float y)
void	text(int num, float x, float y, float z)
void	text(String str, float x, float y)	Advanced
void	text(String str, float x, float y, float z)	Same as above but with a z coordinate.
void	text(String str, float x1, float y1, float x2, float y2)	Advanced
void	textAlign(int alignX)
void	textAlign(int alignX, int alignY)	Sets the current alignment for drawing text.
float	textAscent()	Returns ascent of the current font at its current size.
float	textDescent()	Returns descent of the current font at its current size.
void	textFont(PFont which)	Sets the current font that will be drawn with the text() function.
void	textFont(PFont which, float size)
void	textLeading(float leading)	Sets the spacing between lines of text in units of pixels.
void	textMode(int mode)	Sets the way text draws to the screen, either as texture maps or as vector geometry.
void	textSize(float size)	Sets the current font size.
void	texture(PImage image)	Sets a texture to be applied to vertex points.
void	textureMode(int mode)	Sets the coordinate space for texture mapping.
void	textureWrap(int wrap)	Defines if textures repeat or draw once within a texture map.
float	textWidth(char c)
float	textWidth(char[] chars, int start, int length)
float	textWidth(String str)	Calculates and returns the width of any character or text string.
void	tint(float gray)
void	tint(float gray, float alpha)
void	tint(float v1, float v2, float v3)
void	tint(float v1, float v2, float v3, float alpha)
void	tint(int rgb)	Sets the fill value for displaying images.
void	tint(int rgb, float alpha)
void	translate(float x, float y)	Specifies an amount to displace objects within the display window.
void	translate(float x, float y, float z)
void	triangle(float x1, float y1, float x2, float y2, float x3, float y3)	A triangle is a plane created by connecting three points.
void	vertex(float[] v)	Used by renderer subclasses or PShape to efficiently pass in already formatted vertex information.
void	vertex(float x, float y)
void	vertex(float x, float y, float z)
void	vertex(float x, float y, float u, float v)
void	vertex(float x, float y, float z, float u, float v)	All shapes are constructed by connecting a series of vertices.

Methods inherited from class processing.core.PImage

blend, blend, blendColor, checkAlpha, clone, copy, copy, copy, filter, filter, get, get, get, getImage, getModifiedX1, getModifiedX2, getModifiedY1, getModifiedY2, getNative, init, init, isLoaded, isModified, loadPixels, loadTGA, mask, mask, resize, set, set, setLoaded, setLoaded, setModified, setModified, updatePixels, updatePixels

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

pixelCount

public int pixelCount

width * height (useful for many calculations)

smooth

public int smooth

the anti-aliasing level for renderers that support it

R

public static final int R

See Also:

• Constant Field Values

G

public static final int G

See Also:

• Constant Field Values

B

public static final int B

See Also:

• Constant Field Values

A

public static final int A

See Also:

• Constant Field Values

U

public static final int U

See Also:

• Constant Field Values

V

public static final int V

See Also:

• Constant Field Values

NX

public static final int NX

See Also:

• Constant Field Values

NY

public static final int NY

See Also:

• Constant Field Values

NZ

public static final int NZ

See Also:

• Constant Field Values

EDGE

public static final int EDGE

See Also:

• Constant Field Values

SR

public static final int SR

stroke argb values

See Also:

• Constant Field Values

SG

public static final int SG

See Also:

• Constant Field Values

SB

public static final int SB

See Also:

• Constant Field Values

SA

public static final int SA

See Also:

• Constant Field Values

SW

public static final int SW

stroke weight

See Also:

• Constant Field Values

TX

public static final int TX

See Also:

• Constant Field Values

TY

public static final int TY

See Also:

• Constant Field Values

TZ

public static final int TZ

See Also:

• Constant Field Values

VX

public static final int VX

See Also:

• Constant Field Values

VY

public static final int VY

See Also:

• Constant Field Values

VZ

public static final int VZ

See Also:

• Constant Field Values

VW

public static final int VW

See Also:

• Constant Field Values

AR

public static final int AR

See Also:

• Constant Field Values

AG

public static final int AG

See Also:

• Constant Field Values

AB

public static final int AB

See Also:

• Constant Field Values

DR

public static final int DR

See Also:

• Constant Field Values

DG

public static final int DG

See Also:

• Constant Field Values

DB

public static final int DB

See Also:

• Constant Field Values

DA

public static final int DA

See Also:

• Constant Field Values

SPR

public static final int SPR

See Also:

• Constant Field Values

SPG

public static final int SPG

See Also:

• Constant Field Values

SPB

public static final int SPB

See Also:

• Constant Field Values

SHINE

public static final int SHINE

See Also:

• Constant Field Values

ER

public static final int ER

See Also:

• Constant Field Values

EG

public static final int EG

See Also:

• Constant Field Values

EB

public static final int EB

See Also:

• Constant Field Values

BEEN_LIT

public static final int BEEN_LIT

See Also:

• Constant Field Values

HAS_NORMAL

public static final int HAS_NORMAL

See Also:

• Constant Field Values

VERTEX_FIELD_COUNT

public static final int VERTEX_FIELD_COUNT

See Also:

• Constant Field Values

colorMode

public int colorMode

The current colorMode

colorModeX

public float colorModeX

Max value for red (or hue) set by colorMode

colorModeY

public float colorModeY

Max value for green (or saturation) set by colorMode

colorModeZ

public float colorModeZ

Max value for blue (or value) set by colorMode

colorModeA

public float colorModeA

Max value for alpha set by colorMode

tint

public boolean tint

True if tint() is enabled (read-only).

Using tint/tintColor seems a better option for naming than tintEnabled/tint because the latter seems ugly, even though g.tint as the actual color seems a little more intuitive, it's just that g.tintEnabled is even more unintuitive. Same goes for fill and stroke, et al.

tintColor

public int tintColor

tint that was last set (read-only)

fill

public boolean fill

true if fill() is enabled, (read-only)

fillColor

public int fillColor

fill that was last set (read-only)

stroke

public boolean stroke

true if stroke() is enabled, (read-only)

strokeColor

public int strokeColor

stroke that was last set (read-only)

strokeWeight

public float strokeWeight

Last value set by strokeWeight() (read-only). This has a default setting, rather than fighting with renderers about whether that renderer supports thick lines.

strokeJoin

public int strokeJoin

Set by strokeJoin() (read-only). This has a default setting so that strokeJoin() need not be called by defaults, because subclasses may not implement it (i.e. PGraphicsGL)

strokeCap

public int strokeCap

Set by strokeCap() (read-only). This has a default setting so that strokeCap() need not be called by defaults, because subclasses may not implement it (i.e. PGraphicsGL)

rectMode

public int rectMode

The current rect mode (read-only)

ellipseMode

public int ellipseMode

The current ellipse mode (read-only)

shapeMode

public int shapeMode

The current shape alignment mode (read-only)

imageMode

public int imageMode

The current image alignment (read-only)

textFont

public PFont textFont

The current text font (read-only)

textAlign

public int textAlign

The current text align (read-only)

textAlignY

public int textAlignY

The current vertical text alignment (read-only)

textMode

public int textMode

The current text mode (read-only)

textSize

public float textSize

The current text size (read-only)

textLeading

public float textLeading

The current text leading (read-only)

ambientColor

public int ambientColor

ambientR

public float ambientR

ambientG

public float ambientG

ambientB

public float ambientB

setAmbient

public boolean setAmbient

specularColor

public int specularColor

specularR

public float specularR

specularG

public float specularG

specularB

public float specularB

emissiveColor

public int emissiveColor

emissiveR

public float emissiveR

emissiveG

public float emissiveG

emissiveB

public float emissiveB

shininess

public float shininess

backgroundColor

public int backgroundColor

Last background color that was set, zero if an image

image

public Image image

Java AWT Image object associated with this renderer. For the 1.0 version of P2D and P3D, this was associated with their MemoryImageSource. For PGraphicsJava2D, it will be the offscreen drawing buffer.

DEFAULT_VERTICES

public static final int DEFAULT_VERTICES

See Also:

• Constant Field Values

bezierDetail

public int bezierDetail

curveDetail

public int curveDetail

curveTightness

public float curveTightness

edge

public boolean edge

normalX

public float normalX

Current normal vector.

normalY

public float normalY

Current normal vector.

normalZ

public float normalZ

Current normal vector.

textureMode

public int textureMode

Sets whether texture coordinates passed to vertex() calls will be based on coordinates that are based on the IMAGE or NORMALIZED.

textureU

public float textureU

Current horizontal coordinate for texture, will always be between 0 and 1, even if using textureMode(IMAGE).

textureV

public float textureV

Current vertical coordinate for texture, see above.

textureImage

public PImage textureImage

Current image being used as a texture

sphereDetailU

public int sphereDetailU

sphereDetailV

public int sphereDetailV

Constructor Details

PGraphics

public PGraphics()

Method Details

setParent

public void setParent(PApplet parent)

setPrimary

public void setPrimary(boolean primary)

Set (or unset) this as the main drawing surface. Meaning that it can safely be set to opaque (and given a default gray background), or anything else that goes along with that.

setPath

public void setPath(String path)

setSize

public void setSize(int w,
 int h)

The final step in setting up a renderer, set its size of this renderer. This was formerly handled by the constructor, but instead it's been broken out so that setParent/setPrimary/setPath can be handled differently.

Important: this is ignored by the Methods task because otherwise it will override setSize() in PApplet/Applet/Component, which will 1) not call super.setSize(), and 2) will cause the renderer to be resized from the event thread (EDT), causing a nasty crash as it collides with the animation thread.

dispose

public void dispose()

Handle any shutdown for this graphics context.

This is called when a sketch is shut down and this renderer was specified using the size() command, or inside endRecord() and endRaw(), in order to shut things off.

createSurface

public PSurface createSurface()

setCache

public void setCache(PImage image,
 Object storage)

Store data of some kind for the renderer that requires extra metadata of some kind. Usually this is a renderer-specific representation of the image data, for instance a BufferedImage with tint() settings applied for PGraphicsJava2D, or resized image data and OpenGL texture indices for PGraphicsOpenGL.

Parameters:

image - The image to be stored

storage - The metadata required by the renderer

getCache

public Object getCache(PImage image)

Get cache storage data for the specified renderer. Because each renderer will cache data in different formats, it's necessary to store cache data keyed by the renderer object. Otherwise, attempting to draw the same image to both a PGraphicsJava2D and a PGraphicsOpenGL will cause errors.

Returns:

metadata stored for the specified renderer

removeCache

public void removeCache(PImage image)

Remove information associated with this renderer from the cache, if any.

Parameters:

image - The image whose cache data should be removed

beginDraw

public void beginDraw()

Sets the default properties for a PGraphics object. It should be called before anything is drawn into the object.

Advanced

When creating your own PGraphics, you should call this before drawing anything.

endDraw

public void endDraw()

Finalizes the rendering of a PGraphics object so that it can be shown on screen.

Advanced

When creating your own PGraphics, you should call this when you're finished drawing.

In brief:

Finalizes the rendering of a PGraphics object

beginPGL

public PGL beginPGL()

endPGL

public void endPGL()

flush

public void flush()

hint

public void hint(int which)

Set various hints and hacks for the renderer. This is used to handle obscure rendering features that cannot be implemented in a consistent manner across renderers. Many options will often graduate to standard features instead of hints over time.

hint(ENABLE_OPENGL_4X_SMOOTH)- Enable 4x anti-aliasing for P3D. This can help force anti-aliasing if it has not been enabled by the user. On some graphics cards, this can also be set by the graphics driver's control panel, however not all cards make this available. This hint must be called immediately after the size() command because it resets the renderer, obliterating any settings and anything drawn (and like size(), re-running the code that came before it again).

hint(DISABLE_OPENGL_2X_SMOOTH) - In Processing 1.0, Processing always enables 2x smoothing when the P3D renderer is used. This hint disables the default 2x smoothing and returns the smoothing behavior found in earlier releases, where smooth() and noSmooth() could be used to enable and disable smoothing, though the quality was inferior.

hint(ENABLE_NATIVE_FONTS) - Use the native version fonts when they are installed, rather than the bitmapped version from a .vlw file. This is useful with the default (or JAVA2D) renderer setting, as it will improve font rendering speed. This is not enabled by default, because it can be misleading while testing because the type will look great on your machine (because you have the font installed) but lousy on others' machines if the identical font is unavailable. This option can only be set per-sketch, and must be called before any use of textFont().

hint(DISABLE_DEPTH_TEST) - Disable the zbuffer, allowing you to draw on top of everything at will. When depth testing is disabled, items will be drawn to the screen sequentially, like a painting. This hint is most often used to draw in 3D, then draw in 2D on top of it (for instance, to draw GUI controls in 2D on top of a 3D interface). Starting in release 0149, this will also clear the depth buffer. Restore the default with hint(ENABLE_DEPTH_TEST), but note that with the depth buffer cleared, any 3D drawing that happens later in draw() will ignore existing shapes on the screen.

hint(ENABLE_DEPTH_SORT) - Enable primitive z-sorting of triangles and lines in P3D and OPENGL. This can slow performance considerably, and the algorithm is not yet perfect. Restore the default with hint(DISABLE_DEPTH_SORT).

hint(DISABLE_OPENGL_ERROR_REPORT) - Speeds up the P3D renderer setting by not checking for errors while running. Undo with hint(ENABLE_OPENGL_ERROR_REPORT).

hint(ENABLE_BUFFER_READING) - Depth and stencil buffers in P2D/P3D will be down-sampled to make PGL#readPixels work with multisampling. Enabling this introduces some overhead, so if you experience bad performance, disable multisampling with noSmooth() instead. This hint is not intended to be enabled and disabled repeatedly, so call this once in setup() or after creating your PGraphics2D/3D. You can restore the default with hint(DISABLE_BUFFER_READING) if you don't plan to read depth from this PGraphics anymore.

hint(ENABLE_KEY_REPEAT) - Auto-repeating key events are discarded by default (works only in P2D/P3D); use this hint to get all the key events (including auto-repeated). Call hint(DISABLE_KEY_REPEAT) to get events only when the key goes physically up or down.

hint(DISABLE_ASYNC_SAVEFRAME) - P2D/P3D only - save() and saveFrame() will not use separate threads for saving and will block until the image is written to the drive. This was the default behavior in 3.0b7 and before. To enable, call hint(ENABLE_ASYNC_SAVEFRAME).

Parameters:

which - name of the hint to be enabled or disabled

See Also:

• PGraphics
• PApplet.createGraphics(int, int, String, String)
• PApplet.size(int, int)

beginShape

public void beginShape()

Start a new shape of type POLYGON

beginShape

public void beginShape(int kind)

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.

Parameters:

kind - Either POINTS, LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, QUADS, or QUAD_STRIP

See Also:

• PShape
• endShape()
• vertex(float, float, float, float, float)
• curveVertex(float, float, float)
• bezierVertex(float, float, float, float, float, float, float, float, float)

edge

public void edge(boolean edge)

Sets whether the upcoming vertex is part of an edge. Equivalent to glEdgeFlag(), for people familiar with OpenGL.

normal

public void normal(float nx,
 float ny,
 float nz)

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.

Parameters:

nx - x direction

ny - y direction

nz - z direction

See Also:

• beginShape(int)
• endShape(int)
• lights()

attribPosition

public void attribPosition(String name,
 float x,
 float y,
 float z)

attribNormal

public void attribNormal(String name,
 float nx,
 float ny,
 float nz)

attribColor

public void attribColor(String name,
 int color)

attrib

public void attrib(String name,
 float... values)

attrib

public void attrib(String name,
 int... values)

attrib

public void attrib(String name,
 boolean... values)

textureMode

public void textureMode(int mode)

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).

Parameters:

mode - either IMAGE or NORMAL

See Also:

• texture(PImage)
• textureWrap(int)

textureWrap

public void textureWrap(int wrap)

Defines if textures repeat or draw once within a texture map. The two parameters are CLAMP (the default behavior) and REPEAT. This function only works with the P2D and P3D renderers.

Parameters:

wrap - Either CLAMP (default) or REPEAT

See Also:

• texture(PImage)
• textureMode(int)

texture

public void texture(PImage image)

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.

Parameters:

image - reference to a PImage object

See Also:

• textureMode(int)
• textureWrap(int)
• beginShape(int)
• endShape(int)
• vertex(float, float, float, float, float)

noTexture

public void noTexture()

Removes texture image for current shape. Needs to be called between beginShape and endShape

vertex

public void vertex(float x,
 float y)

vertex

public void vertex(float x,
 float y,
 float z)

vertex

public void vertex(float[] v)

Used by renderer subclasses or PShape to efficiently pass in already formatted vertex information.

Parameters:

v - vertex parameters, as a float array of length VERTEX_FIELD_COUNT

vertex

public void vertex(float x,
 float y,
 float u,
 float v)

vertex

public void vertex(float x,
 float y,
 float z,
 float u,
 float v)

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().

Parameters:

x - x-coordinate of the vertex

y - y-coordinate of the vertex

z - z-coordinate of the vertex

u - horizontal coordinate for the texture mapping

v - vertical coordinate for the texture mapping

See Also:

• beginShape(int)
• endShape(int)
• bezierVertex(float, float, float, float, float, float, float, float, float)
• quadraticVertex(float, float, float, float, float, float)
• curveVertex(float, float, float)
• texture(PImage)

beginContour

public void beginContour()

Use the beginContour() and endContour() function to create negative shapes within shapes such as the center of the letter "O". beginContour() begins recording vertices for the shape and endContour() stops recording. The vertices that define a negative shape must "wind" in the opposite direction from the exterior shape. First draw vertices for the exterior shape in clockwise order, then for internal shapes, draw vertices counterclockwise.

These functions can only be used within a beginShape()/endShape() pair and transformations such as translate(), rotate(), and scale() do not work within a beginContour()/endContour() pair. It is also not possible to use other shapes, such as ellipse() or rect() within.

endContour

public void endContour()

Use the beginContour() and endContour() function to create negative shapes within shapes such as the center of the letter "O". beginContour() begins recording vertices for the shape and endContour() stops recording. The vertices that define a negative shape must "wind" in the opposite direction from the exterior shape. First draw vertices for the exterior shape in clockwise order, then for internal shapes, draw vertices counterclockwise.

These functions can only be used within a beginShape()/endShape() pair and transformations such as translate(), rotate(), and scale() do not work within a beginContour()/endContour() pair. It is also not possible to use other shapes, such as ellipse() or rect() within.

endShape

public void endShape()

endShape

public void endShape(int mode)

The endShape() function is the companion to beginShape() and may only be called after beginShape(). When endshape() is called, all the image data defined since the previous call to beginShape() is written into the image buffer. The constant CLOSE as the value for the MODE parameter to close the shape (to connect the beginning and the end).

Parameters:

mode - use CLOSE to close the shape

See Also:

• PShape
• beginShape(int)

loadShape

public PShape loadShape(String filename)

Loads geometry into a variable of type PShape. SVG and OBJ files may be loaded. To load correctly, the file must be located in the data directory of the current sketch. In most cases, loadShape() should be used inside setup() because loading shapes inside draw() will reduce the speed of a 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.

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.

Parameters:

filename - name of file to load, can be .svg or .obj

See Also:

• PShape
• PApplet.createShape()

loadShape

public PShape loadShape(String filename,
 String options)

createShape

public PShape createShape()

The createShape() function is used to define a new shape. Once created, this shape can be drawn with the shape() function. The basic way to use the function defines new primitive shapes. One of the following parameters are used as the first parameter: ELLIPSE, RECT, ARC, TRIANGLE, SPHERE, BOX, QUAD, or LINE. The parameters for each of these different shapes are the same as their corresponding functions: ellipse(), rect(), arc(), triangle(), sphere(), box(), quad(), and line(). The first example above clarifies how this works.

Custom, unique shapes can be made by using createShape() without a parameter. After the shape is started, the drawing attributes and geometry can be set directly to the shape within the beginShape() and endShape() methods. See the second example above for specifics, and the reference for beginShape() for all of its options.

The createShape() function can also be used to make a complex shape made of other shapes. This is called a "group" and it's created by using the parameter GROUP as the first parameter. See the fourth example above to see how it works.

After using createShape(), stroke and fill color can be set by calling methods like setFill() and setStroke(), as seen in the examples above. The complete list of methods and fields for the PShape class are in the Processing Javadoc.

See Also:

• PShape
• PShape.endShape()
• PApplet.loadShape(String)

createShape

public PShape createShape(int type)

createShape

public PShape createShape(int kind,
 float... p)

Parameters:

kind - either POINT, LINE, TRIANGLE, QUAD, RECT, ELLIPSE, ARC, BOX, SPHERE

p - parameters that match the kind of shape

loadShader

public PShader loadShader(String fragFilename)

Loads a shader into the PShader object. The shader file must be loaded in the sketch's "data" folder/directory to load correctly. Shaders are compatible with the P2D and P3D renderers, but not with the default renderer.

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.

Parameters:

fragFilename - name of fragment shader file

loadShader

public PShader loadShader(String fragFilename,
 String vertFilename)

Parameters:

vertFilename - name of vertex shader file

shader

public void shader(PShader shader)

Applies the shader specified by the parameters. It's compatible with the P2D and P3D renderers, but not with the default renderer.

Parameters:

shader - name of shader file

shader

public void shader(PShader shader,
 int kind)

Parameters:

kind - type of shader, either POINTS, LINES, or TRIANGLES

resetShader

public void resetShader()

Restores the default shaders. Code that runs after resetShader() will not be affected by previously defined shaders.

resetShader

public void resetShader(int kind)

Parameters:

kind - type of shader, either POINTS, LINES, or TRIANGLES

filter

public void filter(PShader shader)

Parameters:

shader - the fragment shader to apply

clip

public void clip(float a,
 float b,
 float c,
 float d)

Limits the rendering to the boundaries of a rectangle defined by the parameters. The boundaries are drawn based on the state of the imageMode() function, either CORNER, CORNERS, or CENTER.

Parameters:

a - x-coordinate of the rectangle, by default

b - y-coordinate of the rectangle, by default

c - width of the rectangle, by default

d - height of the rectangle, by default

noClip

public void noClip()

Disables the clipping previously started by the clip() function.

blendMode

public void blendMode(int mode)

Blends the pixels in the display window according to a defined mode. There is a choice of the following modes to blend the source pixels (A) with the ones of pixels already in the display window (B). Each pixel's final color is the result of applying one of the blend modes with each channel of (A) and (B) independently. The red channel is compared with red, green with green, and blue with blue.

BLEND - linear interpolation of colors: C = A*factor + B. This is the default.

ADD - additive blending with white clip: C = min(A*factor + B, 255)

SUBTRACT - subtractive blending with black clip: C = max(B - A*factor, 0)

DARKEST - only the darkest color succeeds: C = min(A*factor, B)

LIGHTEST - only the lightest color succeeds: C = max(A*factor, B)

DIFFERENCE - subtract colors from underlying image.

EXCLUSION - similar to DIFFERENCE, but less extreme.

MULTIPLY - multiply the colors, result will always be darker.

SCREEN - opposite multiply, uses inverse values of the colors.

REPLACE - the pixels entirely replace the others and don't utilize alpha (transparency) values

We recommend using blendMode() and not the previous blend() function. However, unlike blend(), the blendMode() function does not support the following: HARD_LIGHT, SOFT_LIGHT, OVERLAY, DODGE, BURN. On older hardware, the LIGHTEST, DARKEST, and DIFFERENCE modes might not be available as well.

Parameters:

mode - the blending mode to use

bezierVertex

public void bezierVertex(float x2,
 float y2,
 float x3,
 float y3,
 float x4,
 float y4)

bezierVertex

public void bezierVertex(float x2,
 float y2,
 float z2,
 float x3,
 float y3,
 float z3,
 float x4,
 float y4,
 float z4)

Specifies vertex coordinates for Bézier curves. Each call to bezierVertex() defines the position of two control points and one anchor point of a Bézier curve, adding a new segment to a line or shape. The first time bezierVertex() is used within a beginShape() call, it must be prefaced with a call to vertex() to set the first anchor point. This function must be used between beginShape() and endShape() and only when there is no MODE parameter specified to beginShape(). Using the 3D version requires rendering with P3D (see the Environment reference for more information).

Parameters:

x2 - the x-coordinate of the 1st control point

y2 - the y-coordinate of the 1st control point

z2 - the z-coordinate of the 1st control point

x3 - the x-coordinate of the 2nd control point

y3 - the y-coordinate of the 2nd control point

z3 - the z-coordinate of the 2nd control point

x4 - the x-coordinate of the anchor point

y4 - the y-coordinate of the anchor point

z4 - the z-coordinate of the anchor point

See Also:

• curveVertex(float, float, float)
• vertex(float, float, float, float, float)
• quadraticVertex(float, float, float, float, float, float)
• bezier(float, float, float, float, float, float, float, float, float, float, float, float)

quadraticVertex

public void quadraticVertex(float cx,
 float cy,
 float x3,
 float y3)

Specifies vertex coordinates for quadratic Bézier curves. Each call to quadraticVertex() defines the position of one control point and one anchor point of a Bézier curve, adding a new segment to a line or shape. The first time quadraticVertex() is used within a beginShape() call, it must be prefaced with a call to vertex() to set the first anchor point. This function must be used between beginShape() and endShape() and only when there is no MODE parameter specified to beginShape(). Using the 3D version requires rendering with P3D (see the Environment reference for more information).

Parameters:

cx - the x-coordinate of the control point

cy - the y-coordinate of the control point

x3 - the x-coordinate of the anchor point

y3 - the y-coordinate of the anchor point

See Also:

• curveVertex(float, float, float)
• vertex(float, float, float, float, float)
• bezierVertex(float, float, float, float, float, float)
• bezier(float, float, float, float, float, float, float, float, float, float, float, float)

quadraticVertex

public void quadraticVertex(float cx,
 float cy,
 float cz,
 float x3,
 float y3,
 float z3)

Parameters:

cz - the z-coordinate of the control point

z3 - the z-coordinate of the anchor point

curveVertex

public void curveVertex(float x,
 float y)

Specifies vertex coordinates for curves. This function may only be used between beginShape() and endShape() and only when there is no MODE parameter specified to beginShape(). The first and last points in a series of curveVertex() lines will be used to guide the beginning and end of the curve. A minimum of four points is required to draw a tiny curve between the second and third points. Adding a fifth point with curveVertex() will draw the curve between the second, third, and fourth points. The curveVertex() function is an implementation of Catmull-Rom splines. Using the 3D version requires rendering with P3D (see the Environment reference for more information).

Parameters:

x - the x-coordinate of the vertex

y - the y-coordinate of the vertex

See Also:

• curve(float, float, float, float, float, float, float, float, float, float, float, float)
• beginShape(int)
• endShape(int)
• vertex(float, float, float, float, float)
• bezier(float, float, float, float, float, float, float, float, float, float, float, float)
• quadraticVertex(float, float, float, float, float, float)

curveVertex

public void curveVertex(float x,
 float y,
 float z)

Parameters:

z - the z-coordinate of the vertex

point

public void point(float x,
 float y)

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().

Parameters:

x - x-coordinate of the point

y - y-coordinate of the point

See Also:

• stroke(int)

point

public void point(float x,
 float y,
 float z)

Parameters:

z - z-coordinate of the point

line

public void line(float x1,
 float y1,
 float x2,
 float y2)

Draws a line (a direct path between two points) to the screen. The version of line() with four parameters draws the line in 2D. To color a line, use the stroke() function. A line cannot be filled, therefore the fill() function will not affect the color of a line. 2D lines are drawn with a width of one pixel by default, but this can be changed with the strokeWeight() function. The version with six parameters allows the line to be placed anywhere within XYZ space. Drawing this shape in 3D with the z parameter requires the P3D parameter in combination with size() as shown in the above example.

Parameters:

x1 - x-coordinate of the first point

y1 - y-coordinate of the first point

x2 - x-coordinate of the second point

y2 - y-coordinate of the second point

See Also:

• strokeWeight(float)
• strokeJoin(int)
• strokeCap(int)
• beginShape()

line

public void line(float x1,
 float y1,
 float z1,
 float x2,
 float y2,
 float z2)

Parameters:

z1 - z-coordinate of the first point

z2 - z-coordinate of the second point

triangle

public void triangle(float x1,
 float y1,
 float x2,
 float y2,
 float x3,
 float y3)

A triangle is a plane created by connecting three points. The first two arguments specify the first point, the middle two arguments specify the second point, and the last two arguments specify the third point.

Parameters:

x1 - x-coordinate of the first point

y1 - y-coordinate of the first point

x2 - x-coordinate of the second point

y2 - y-coordinate of the second point

x3 - x-coordinate of the third point

y3 - y-coordinate of the third point

See Also:

• PApplet.beginShape()

quad

public void quad(float x1,
 float y1,
 float x2,
 float y2,
 float x3,
 float y3,
 float x4,
 float y4)

A quad is a quadrilateral, a four sided polygon. It is similar to a rectangle, but the angles between its edges are not constrained to ninety degrees. The first pair of parameters (x1,y1) sets the first vertex and the subsequent pairs should proceed clockwise or counter-clockwise around the defined shape.

Parameters:

x1 - x-coordinate of the first corner

y1 - y-coordinate of the first corner

x2 - x-coordinate of the second corner

y2 - y-coordinate of the second corner

x3 - x-coordinate of the third corner

y3 - y-coordinate of the third corner

x4 - x-coordinate of the fourth corner

y4 - y-coordinate of the fourth corner

rectMode

public void rectMode(int mode)

Modifies the location from which rectangles are drawn by changing the way in which parameters given to rect() are interpreted.

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 shape's width and height.

The parameter must be written in ALL CAPS because Processing is a case-sensitive language.

Parameters:

mode - either CORNER, CORNERS, CENTER, or RADIUS

See Also:

• rect(float, float, float, float)

rect

public void rect(float a,
 float b,
 float c,
 float d)

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.

Parameters:

a - x-coordinate of the rectangle by default

b - y-coordinate of the rectangle by default

c - width of the rectangle by default

d - height of the rectangle by default

See Also:

• rectMode(int)
• quad(float, float, float, float, float, float, float, float)

rect

public void rect(float a,
 float b,
 float c,
 float d,
 float r)

Parameters:

r - radii for all four corners

rect

public void rect(float a,
 float b,
 float c,
 float d,
 float tl,
 float tr,
 float br,
 float bl)

Parameters:

tl - radius for top-left corner

tr - radius for top-right corner

br - radius for bottom-right corner

bl - radius for bottom-left corner

square

public void square(float x,
 float y,
 float extent)

Draws a square to the screen. A square is a four-sided shape with every angle at ninety degrees and each side is the same length. By default, the first two parameters set the location of the upper-left corner, the third sets the width and height. The way these parameters are interpreted, however, may be changed with the rectMode() function.

Parameters:

x - x-coordinate of the rectangle by default

y - y-coordinate of the rectangle by default

extent - width and height of the rectangle by default

See Also:

• rect(float, float, float, float)
• rectMode(int)

ellipseMode

public void ellipseMode(int mode)

Modifies the location from which ellipses are drawn by changing the way in which parameters given to ellipse() are interpreted.

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 shape'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.

Parameters:

mode - either CENTER, RADIUS, CORNER, or CORNERS

See Also:

• PApplet.ellipse(float, float, float, float)
• PApplet.arc(float, float, float, float, float, float)

ellipse

public void ellipse(float a,
 float b,
 float c,
 float d)

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.

Parameters:

a - x-coordinate of the ellipse

b - y-coordinate of the ellipse

c - width of the ellipse by default

d - height of the ellipse by default

See Also:

• PApplet.ellipseMode(int)
• PApplet.arc(float, float, float, float, float, float)

arc

public void arc(float a,
 float b,
 float c,
 float d,
 float start,
 float stop)

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.

Parameters:

a - x-coordinate of the arc's ellipse

b - y-coordinate of the arc's ellipse

c - width of the arc's ellipse by default

d - height of the arc's ellipse by default

start - angle to start the arc, specified in radians

stop - angle to stop the arc, specified in radians

See Also:

• PApplet.ellipse(float, float, float, float)
• PApplet.ellipseMode(int)
• PApplet.radians(float)
• PApplet.degrees(float)

arc

public void arc(float a,
 float b,
 float c,
 float d,
 float start,
 float stop,
 int mode)

circle

public void circle(float x,
 float y,
 float extent)

Draws a circle to the screen. By default, the first two parameters set the location of the center, and the third sets the shape's width and height. The origin may be changed with the ellipseMode() function.

Parameters:

x - x-coordinate of the ellipse

y - y-coordinate of the ellipse

extent - width and height of the ellipse by default

See Also:

• PApplet.ellipse(float, float, float, float)
• PApplet.ellipseMode(int)

box

public void box(float size)

A box is an extruded rectangle. A box with equal dimension on all sides is a cube.

Parameters:

size - dimension of the box in all dimensions (creates a cube)

See Also:

• sphere(float)

box

public void box(float w,
 float h,
 float d)

Parameters:

w - dimension of the box in the x-dimension

h - dimension of the box in the y-dimension

d - dimension of the box in the z-dimension

sphereDetail

public void sphereDetail(int res)

Controls the detail used to render a sphere by adjusting the number of vertices of the sphere mesh. The default resolution is 30, which creates a fairly detailed sphere definition with vertices every 360/30 = 12 degrees. If you're going to render a great number of spheres per frame, it is advised to reduce the level of detail using this function. The setting stays active until sphereDetail() is called again with a new parameter and so should not be called prior to every sphere() statement, unless you wish to render spheres with different settings, e.g. using less detail for smaller spheres or ones further away from the camera. To control the detail of the horizontal and vertical resolution independently, use the version of the functions with two parameters.

Advanced

Code for sphereDetail() submitted by toxi [031031]. Code for enhanced u/v version from davbol [080801].

Parameters:

res - number of segments (minimum 3) used per full circle revolution

See Also:

• sphere(float)

sphereDetail

public void sphereDetail(int ures,
 int vres)

Parameters:

ures - number of segments used longitudinally per full circle revolution

vres - number of segments used latitudinally from top to bottom

sphere

public void sphere(float r)

A sphere is a hollow ball made from tessellated triangles.

Advanced

Implementation notes:

cache all the points of the sphere in a static array top and bottom are just a bunch of triangles that land in the center point

sphere is a series of concentric circles who radii vary along the shape, based on, err... cos or something

 [toxi 031031] new sphere code. removed all multiplies with
 radius, as scale() will take care of that anyway

 [toxi 031223] updated sphere code (removed modulo)
 and introduced sphereAt(x,y,z,r)
 to avoid additional translate()'s on the user/sketch side

 [davbol 080801] now using separate sphereDetailU/V
 

Parameters:

r - the radius of the sphere

See Also:

• sphereDetail(int)

bezierPoint

public float bezierPoint(float a,
 float b,
 float c,
 float d,
 float t)

Evaluates the Bezier at point t for points a, b, c, d. The parameter t varies between 0 and 1, a and d are points on the curve, and b and c are the control points. This can be done once with the x coordinates and a second time with the y coordinates to get the location of a Bézier curve at t.

Advanced

For instance, to convert the following example:

 stroke(255, 102, 0);
 line(85, 20, 10, 10);
 line(90, 90, 15, 80);
 stroke(0, 0, 0);
 bezier(85, 20, 10, 10, 90, 90, 15, 80);

 // draw it in gray, using 10 steps instead of the default 20
 // this is a slower way to do it, but useful if you need
 // to do things with the coordinates at each step
 stroke(128);
 beginShape(LINE_STRIP);
 for (int i = 0; i <= 10; i++) {
   float t = i / 10.0f;
   float x = bezierPoint(85, 10, 90, 15, t);
   float y = bezierPoint(20, 10, 90, 80, t);
   vertex(x, y);
 }
 endShape();

Parameters:

a - coordinate of first point on the curve

b - coordinate of first control point

c - coordinate of second control point

d - coordinate of second point on the curve

t - value between 0 and 1

See Also:

• bezier(float, float, float, float, float, float, float, float, float, float, float, float)
• bezierVertex(float, float, float, float, float, float)
• curvePoint(float, float, float, float, float)

bezierTangent

public float bezierTangent(float a,
 float b,
 float c,
 float d,
 float t)

Calculates the tangent of a point on a Bézier curve. There is a good definition of tangent on Wikipedia.

Advanced

Code submitted by Dave Bollinger (davbol) for release 0136.

Parameters:

a - coordinate of first point on the curve

b - coordinate of first control point

c - coordinate of second control point

d - coordinate of second point on the curve

t - value between 0 and 1

See Also:

• bezier(float, float, float, float, float, float, float, float, float, float, float, float)
• bezierVertex(float, float, float, float, float, float)
• curvePoint(float, float, float, float, float)

bezierDetail

public void bezierDetail(int detail)

Sets the resolution at which Bézier curves display. The default value is 20. This function is only useful when using the P2D or P3D renderer; the default (JAVA2D) renderer does not use this information.

Parameters:

detail - resolution of the curves

See Also:

• curve(float, float, float, float, float, float, float, float, float, float, float, float)
• curveVertex(float, float, float)
• curveTightness(float)

bezier

public void bezier(float x1,
 float y1,
 float x2,
 float y2,
 float x3,
 float y3,
 float x4,
 float y4)

bezier

public void bezier(float x1,
 float y1,
 float z1,
 float x2,
 float y2,
 float z2,
 float x3,
 float y3,
 float z3,
 float x4,
 float y4,
 float z4)

Draws a Bézier curve on the screen. These curves are defined by a series of anchor and control points. The first two parameters specify the first anchor point and the last two parameters specify the other anchor point. The middle parameters specify the control points which define the shape of the curve. The curves were developed by French engineer Pierre Bezier. Using the 3D version requires rendering with P3D (see the Environment reference for more information).

Advanced

Draw a cubic Bézier curve. The first and last points are the on-curve points. The middle two are the 'control' points, or 'handles' in an application like Illustrator.

Identical to typing:

beginShape();
 vertex(x1, y1);
 bezierVertex(x2, y2, x3, y3, x4, y4);
 endShape();
 

In Postscript-speak, this would be:

moveto(x1, y1);
 curveto(x2, y2, x3, y3, x4, y4);

If you were to try and continue that curve like so:

curveto(x5, y5, x6, y6, x7, y7);

This would be done in processing by adding these statements:

bezierVertex(x5, y5, x6, y6, x7, y7)
 

To draw a quadratic (instead of cubic) curve, use the control point twice by doubling it:

bezier(x1, y1, cx, cy, cx, cy, x2, y2);

Parameters:

x1 - coordinates for the first anchor point

y1 - coordinates for the first anchor point

z1 - coordinates for the first anchor point

x2 - coordinates for the first control point

y2 - coordinates for the first control point

z2 - coordinates for the first control point

x3 - coordinates for the second control point

y3 - coordinates for the second control point

z3 - coordinates for the second control point

x4 - coordinates for the second anchor point

y4 - coordinates for the second anchor point

z4 - coordinates for the second anchor point

See Also:

• bezierVertex(float, float, float, float, float, float)
• curve(float, float, float, float, float, float, float, float, float, float, float, float)

curvePoint

public float curvePoint(float a,
 float b,
 float c,
 float d,
 float t)

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.

Parameters:

a - coordinate of first control point

b - coordinate of first point on the curve

c - coordinate of second point on the curve

d - coordinate of second control point

t - value between 0 and 1

See Also:

• curve(float, float, float, float, float, float, float, float, float, float, float, float)
• curveVertex(float, float)
• bezierPoint(float, float, float, float, float)

curveTangent

public float curveTangent(float a,
 float b,
 float c,
 float d,
 float t)

Calculates the tangent of a point on a curve. There's a good definition of tangent on Wikipedia.

Advanced

Code thanks to Dave Bollinger (Bug #715)

Parameters:

a - coordinate of first point on the curve

b - coordinate of first control point

c - coordinate of second control point

d - coordinate of second point on the curve

t - value between 0 and 1

See Also:

• curve(float, float, float, float, float, float, float, float, float, float, float, float)
• curveVertex(float, float)
• curvePoint(float, float, float, float, float)
• bezierTangent(float, float, float, float, float)

curveDetail

public void curveDetail(int detail)

Sets the resolution at which curves 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.

Parameters:

detail - resolution of the curves

See Also:

• curve(float, float, float, float, float, float, float, float, float, float, float, float)
• curveVertex(float, float)
• curveTightness(float)

curveTightness

public void curveTightness(float tightness)

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.

Parameters:

tightness - amount of deformation from the original vertices

See Also:

• curve(float, float, float, float, float, float, float, float, float, float, float, float)
• curveVertex(float, float)

curve

public void curve(float x1,
 float y1,
 float x2,
 float y2,
 float x3,
 float y3,
 float x4,
 float y4)

Draws a curved line on the screen. The first and second parameters specify the beginning control point and the last two parameters specify the ending control point. The middle parameters specify the start and stop of the curve. Longer curves can be created by putting a series of curve() functions together or using curveVertex(). An additional function called curveTightness() provides control for the visual quality of the curve. The curve() function is an implementation of Catmull-Rom splines. Using the 3D version requires rendering with P3D (see the Environment reference for more information).

Advanced

As of revision 0070, this function no longer doubles the first and last points. The curves are a bit more boring, but it's more mathematically correct, and properly mirrored in curvePoint().

Identical to typing out:

 beginShape();
 curveVertex(x1, y1);
 curveVertex(x2, y2);
 curveVertex(x3, y3);
 curveVertex(x4, y4);
 endShape();
 

Parameters:

x1 - coordinates for the beginning control point

y1 - coordinates for the beginning control point

x2 - coordinates for the first point

y2 - coordinates for the first point

x3 - coordinates for the second point

y3 - coordinates for the second point

x4 - coordinates for the ending control point

y4 - coordinates for the ending control point

See Also:

• curveVertex(float, float)
• curveTightness(float)
• bezier(float, float, float, float, float, float, float, float, float, float, float, float)

curve

public void curve(float x1,
 float y1,
 float z1,
 float x2,
 float y2,
 float z2,
 float x3,
 float y3,
 float z3,
 float x4,
 float y4,
 float z4)

Parameters:

z1 - coordinates for the beginning control point

z2 - coordinates for the first point

z3 - coordinates for the second point

z4 - coordinates for the ending control point

smooth

public void smooth()

smooth

public void smooth(int quality)

noSmooth

public void noSmooth()

imageMode

public void imageMode(int mode)

Modifies the location from which images are drawn by changing the way in which parameters given to image() are interpreted.

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.

Parameters:

mode - either CORNER, CORNERS, or CENTER

See Also:

• PApplet.loadImage(String, String)
• PImage
• image(PImage, float, float, float, float)
• background(float, float, float, float)

image

public void image(PImage img,
 float a,
 float b)

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.

Parameters:

img - the image to display

a - x-coordinate of the image by default

b - y-coordinate of the image by default

See Also:

• PApplet.loadImage(String, String)
• PImage
• imageMode(int)
• tint(float)
• background(float, float, float, float)
• alpha(int)

image

public void image(PImage img,
 float a,
 float b,
 float c,
 float d)

Parameters:

c - width to display the image by default

d - height to display the image by default

image

public void image(PImage img,
 float a,
 float b,
 float c,
 float d,
 int u1,
 int v1,
 int u2,
 int v2)

Draw an image(), also specifying u/v coordinates. In this method, the u, v coordinates are always based on image space location, regardless of the current textureMode().

shapeMode

public void shapeMode(int mode)

Modifies the location from which shapes draw. The default mode is shapeMode(CORNER), which specifies the location to be the upper left corner of the shape and uses the third and fourth parameters of shape() to specify the width and height. The syntax shapeMode(CORNERS) uses the first and second parameters of shape() to set the location of one corner and uses the third and fourth parameters to set the opposite corner. The syntax shapeMode(CENTER) draws the shape from its center point and uses the third and forth parameters of shape() to specify the width and height. The parameter must be written in "ALL CAPS" because Processing is a case-sensitive language.

Parameters:

mode - either CORNER, CORNERS, CENTER

See Also:

• PShape
• shape(PShape)
• rectMode(int)

shape

public void shape(PShape shape)

shape

public void shape(PShape shape,
 float x,
 float y)

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.

Parameters:

shape - the shape to display

x - x-coordinate of the shape

y - y-coordinate of the shape

See Also:

• PShape
• PApplet.loadShape(String)
• shapeMode(int)

shape

public void shape(PShape shape,
 float a,
 float b,
 float c,
 float d)

Parameters:

a - x-coordinate of the shape

b - y-coordinate of the shape

c - width to display the shape

d - height to display the shape

textAlign

public void textAlign(int alignX)

textAlign

public void textAlign(int alignX,
 int alignY)

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.

Parameters:

alignX - horizontal alignment, either LEFT, CENTER, or RIGHT

alignY - vertical alignment, either TOP, BOTTOM, CENTER, or BASELINE

See Also:

• PApplet.loadFont(String)
• PFont
• text(String, float, float)
• textSize(float)
• textAscent()
• textDescent()

textAscent

public float textAscent()

Returns ascent of the current font at its current size. This information is useful for determining the height of the font above the baseline.

See Also:

• textDescent()

textDescent

public float textDescent()

Returns descent of the current font at its current size. This information is useful for determining the height of the font below the baseline.

See Also:

• textAscent()

textFont

public void textFont(PFont which)

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.

Parameters:

which - any variable of the type PFont

See Also:

• PApplet.createFont(String, float, boolean)
• PApplet.loadFont(String)
• PFont
• text(String, float, float)
• textSize(float)

textFont

public void textFont(PFont which,
 float size)

Parameters:

size - the size of the letters in units of pixels

textLeading

public void textLeading(float leading)

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.

Parameters:

leading - the size in pixels for spacing between lines

See Also:

• PApplet.loadFont(String)
• PFont(java.io.InputStream)
• text(String, float, float)
• textFont(PFont)
• textSize(float)

textMode

public void textMode(int mode)

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().

Parameters:

mode - either MODEL or SHAPE

See Also:

• PApplet.loadFont(String)
• PFont(java.io.InputStream)
• text(String, float, float)
• textFont(PFont)
• beginRaw(PGraphics)
• PApplet.createFont(String, float, boolean)

textSize

public void textSize(float size)

Sets the current font size. This size will be used in all subsequent calls to the text() function. Font size is measured in units of pixels.

Parameters:

size - the size of the letters in units of pixels

See Also:

• PApplet.loadFont(String)
• PFont(java.io.InputStream)
• text(String, float, float)
• textFont(PFont)

textWidth

public float textWidth(char c)

Parameters:

c - the character to measure

textWidth

public float textWidth(String str)

Calculates and returns the width of any character or text string.

Parameters:

str - the String of characters to measure

See Also:

• PApplet.loadFont(String)
• PFont(java.io.InputStream)
• text(String, float, float)
• textFont(PFont)
• textSize(float)

textWidth

public float textWidth(char[] chars,
 int start,
 int length)

text

public void text(char c,
 float x,
 float y)

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.)

Parameters:

c - the alphanumeric character to be displayed

x - x-coordinate of text

y - y-coordinate of text

See Also:

• textAlign(int, int)
• textFont(PFont)
• textMode(int)
• textSize(float)
• textLeading(float)
• textWidth(String)
• textAscent()
• textDescent()
• rectMode(int)
• fill(int, float)

text

public void text(char c,
 float x,
 float y,
 float z)

Parameters:

z - z-coordinate of text

text

public void text(String str,
 float x,
 float y)

Advanced

Draw a chunk of text. Newlines that are \n (Unix newline or linefeed char, ascii 10) are honored, but \r (carriage return, Windows and Mac OS) are ignored.

text

public void text(char[] chars,
 int start,
 int stop,
 float x,
 float y)

Advanced

Method to draw text from an array of chars. This method will usually be more efficient than drawing from a String object, because the String will not be converted to a char array before drawing.

Parameters:

chars - the alphanumeric symbols to be displayed

start - array index at which to start writing characters

stop - array index at which to stop writing characters

text

public void text(String str,
 float x,
 float y,
 float z)

Same as above but with a z coordinate.

text

public void text(char[] chars,
 int start,
 int stop,
 float x,
 float y,
 float z)

text

public void text(String str,
 float x1,
 float y1,
 float x2,
 float y2)

Advanced

Draw text in a box that is constrained to a particular size. The current rectMode() determines what the coordinates mean (whether x1/y1/x2/y2 or x/y/w/h).

Note that the x,y coords of the start of the box will align with the *ascent* of the text, not the baseline, as is the case for the other text() functions.

Newlines that are \n (Unix newline or linefeed char, ascii 10) are honored, and \r (carriage return, Windows and Mac OS) are ignored.

Parameters:

x1 - by default, the x-coordinate of text, see rectMode() for more info

y1 - by default, the y-coordinate of text, see rectMode() for more info

x2 - by default, the width of the text box, see rectMode() for more info

y2 - by default, the height of the text box, see rectMode() for more info

text

public void text(int num,
 float x,
 float y)

text

public void text(int num,
 float x,
 float y,
 float z)

text

public void text(float num,
 float x,
 float y)

This does a basic number formatting, to avoid the generally ugly appearance of printing floats. Users who want more control should use their own nf() command, or if they want the long, ugly version of float, use String.valueOf() to convert the float to a String first.

Parameters:

num - the numeric value to be displayed

text

public void text(float num,
 float x,
 float y,
 float z)

push

public void push()

The push() function saves the current drawing style settings and transformations, while pop() restores these settings. 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.

push() stores information related to the current transformation state and style settings controlled by the following functions: rotate(), translate(), scale(), fill(), stroke(), tint(), strokeWeight(), strokeCap(), strokeJoin(), imageMode(), rectMode(), ellipseMode(), colorMode(), textAlign(), textFont(), textMode(), textSize(), textLeading().

The push() and pop() functions were added with Processing 3.5. They can be used in place of pushMatrix(), popMatrix(), pushStyles(), and popStyles(). The difference is that push() and pop() control both the transformations (rotate, scale, translate) and the drawing styles at the same time.

See Also:

• pop()

pop

public void pop()

The pop() function restores the previous drawing style settings and transformations after push() has changed them. 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.

push() stores information related to the current transformation state and style settings controlled by the following functions: rotate(), translate(), scale(), fill(), stroke(), tint(), strokeWeight(), strokeCap(), strokeJoin(), imageMode(), rectMode(), ellipseMode(), colorMode(), textAlign(), textFont(), textMode(), textSize(), textLeading().

The push() and pop() functions were added with Processing 3.5. They can be used in place of pushMatrix(), popMatrix(), pushStyles(), and popStyles(). The difference is that push() and pop() control both the transformations (rotate, scale, translate) and the drawing styles at the same time.

See Also:

• push()

pushMatrix

public void pushMatrix()

Pushes the current transformation matrix onto the matrix stack. Understanding pushMatrix() and popMatrix() requires understanding the concept of a matrix stack. The pushMatrix() function saves the current coordinate system to the stack and popMatrix() restores the prior coordinate system. pushMatrix() and popMatrix() are used in conjunction with the other transformation functions and may be embedded to control the scope of the transformations.

See Also:

• popMatrix()
• translate(float, float, float)
• scale(float)
• rotate(float)
• rotateX(float)
• rotateY(float)
• rotateZ(float)

popMatrix

public void popMatrix()

Pops the current transformation matrix off the matrix stack. Understanding pushing and popping requires understanding the concept of a matrix stack. The pushMatrix() function saves the current coordinate system to the stack and popMatrix() restores the prior coordinate system. pushMatrix() and popMatrix() are used in conjunction with the other transformation functions and may be embedded to control the scope of the transformations.

See Also:

• pushMatrix()

translate

public void translate(float x,
 float y)

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().

Parameters:

x - left/right translation

y - up/down translation

See Also:

• popMatrix()
• pushMatrix()
• rotate(float)
• rotateX(float)
• rotateY(float)
• rotateZ(float)
• scale(float, float, float)

translate

public void translate(float x,
 float y,
 float z)

Parameters:

z - forward/backward translation

rotate

public void rotate(float angle)

Rotates a shape the amount specified by the angle parameter. Angles should be specified in radians (values from 0 to TWO_PI) or converted to radians with the radians() function.

Objects are always rotated around their relative position to the origin and positive numbers rotate objects in a clockwise direction. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling rotate(HALF_PI) and then rotate(HALF_PI) is the same as rotate(PI). All transformations are reset when draw() begins again.

Technically, rotate() multiplies the current transformation matrix by a rotation matrix. This function can be further controlled by the pushMatrix() and popMatrix().

Parameters:

angle - angle of rotation specified in radians

See Also:

• popMatrix()
• pushMatrix()
• rotateX(float)
• rotateY(float)
• rotateZ(float)
• scale(float, float, float)
• PApplet.radians(float)

rotateX

public void rotateX(float angle)

Rotates a shape around the x-axis the amount specified by the angle parameter. Angles should be specified in radians (values from 0 to PI*2) or converted to radians with the radians() function. Objects are always rotated around their relative position to the origin and positive numbers rotate objects in a counterclockwise direction. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling rotateX(PI/2) and then rotateX(PI/2) is the same as rotateX(PI). If rotateX() is called within the draw(), the transformation is reset when the loop begins again. This function requires using P3D as a third parameter to size() as shown in the example above.

Parameters:

angle - angle of rotation specified in radians

See Also:

• popMatrix()
• pushMatrix()
• rotate(float)
• rotateY(float)
• rotateZ(float)
• scale(float, float, float)
• translate(float, float, float)

rotateY

public void rotateY(float angle)

Rotates a shape around the y-axis the amount specified by the angle parameter. Angles should be specified in radians (values from 0 to PI*2) or converted to radians with the radians() function. Objects are always rotated around their relative position to the origin and positive numbers rotate objects in a counterclockwise direction. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling rotateY(PI/2) and then rotateY(PI/2) is the same as rotateY(PI). If rotateY() is called within the draw(), the transformation is reset when the loop begins again. This function requires using P3D as a third parameter to size() as shown in the examples above.

Parameters:

angle - angle of rotation specified in radians

See Also:

• popMatrix()
• pushMatrix()
• rotate(float)
• rotateX(float)
• rotateZ(float)
• scale(float, float, float)
• translate(float, float, float)

rotateZ

public void rotateZ(float angle)

Rotates a shape around the z-axis the amount specified by the angle parameter. Angles should be specified in radians (values from 0 to PI*2) or converted to radians with the radians() function. Objects are always rotated around their relative position to the origin and positive numbers rotate objects in a counterclockwise direction. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling rotateZ(PI/2) and then rotateZ(PI/2) is the same as rotateZ(PI). If rotateZ() is called within the draw(), the transformation is reset when the loop begins again. This function requires using P3D as a third parameter to size() as shown in the examples above.

Parameters:

angle - angle of rotation specified in radians

See Also:

• popMatrix()
• pushMatrix()
• rotate(float)
• rotateX(float)
• rotateY(float)
• scale(float, float, float)
• translate(float, float, float)

rotate

public void rotate(float angle,
 float x,
 float y,
 float z)

Advanced

Rotate about a vector in space. Same as the glRotatef() function.

scale

public void scale(float s)

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().

Parameters:

s - percentage to scale the object

See Also:

• pushMatrix()
• popMatrix()
• translate(float, float, float)
• rotate(float)
• rotateX(float)
• rotateY(float)
• rotateZ(float)

scale

public void scale(float x,
 float y)

Advanced

Scale in X and Y. Equivalent to scale(sx, sy, 1).

Not recommended for use in 3D, because the z-dimension is just scaled by 1, since there's no way to know what else to scale it by.

Parameters:

x - percentage to scale the object in the x-axis

y - percentage to scale the object in the y-axis

scale

public void scale(float x,
 float y,
 float z)

Parameters:

z - percentage to scale the object in the z-axis

shearX

public void shearX(float angle)

Shears a shape around the x-axis the amount specified by the angle parameter. Angles should be specified in radians (values from 0 to PI*2) or converted to radians with the radians() function. Objects are always sheared around their relative position to the origin and positive numbers shear objects in a clockwise direction. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling shearX(PI/2) and then shearX(PI/2) is the same as shearX(PI). If shearX() is called within the draw(), the transformation is reset when the loop begins again.

Technically, shearX() multiplies the current transformation matrix by a rotation matrix. This function can be further controlled by the pushMatrix() and popMatrix() functions.

Parameters:

angle - angle of shear specified in radians

See Also:

• popMatrix()
• pushMatrix()
• shearY(float)
• scale(float, float, float)
• translate(float, float, float)
• PApplet.radians(float)

shearY

public void shearY(float angle)

Shears a shape around the y-axis the amount specified by the angle parameter. Angles should be specified in radians (values from 0 to PI*2) or converted to radians with the radians() function. Objects are always sheared around their relative position to the origin and positive numbers shear objects in a clockwise direction. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling shearY(PI/2) and then shearY(PI/2) is the same as shearY(PI). If shearY() is called within the draw(), the transformation is reset when the loop begins again.

Technically, shearY() multiplies the current transformation matrix by a rotation matrix. This function can be further controlled by the pushMatrix() and popMatrix() functions.

Parameters:

angle - angle of shear specified in radians

See Also:

• popMatrix()
• pushMatrix()
• shearX(float)
• scale(float, float, float)
• translate(float, float, float)
• PApplet.radians(float)

resetMatrix

public void resetMatrix()

Replaces the current matrix with the identity matrix. The equivalent function in OpenGL is glLoadIdentity().

See Also:

• pushMatrix()
• popMatrix()
• applyMatrix(PMatrix)
• printMatrix()

applyMatrix

public void applyMatrix(PMatrix source)

Multiplies the current matrix by the one specified through the parameters. This is very slow because it will try to calculate the inverse of the transform, so avoid it whenever possible. The equivalent function in OpenGL is glMultMatrix().

See Also:

• pushMatrix()
• popMatrix()
• resetMatrix()
• printMatrix()

applyMatrix

public void applyMatrix(PMatrix2D source)

applyMatrix

public void applyMatrix(float n00,
 float n01,
 float n02,
 float n10,
 float n11,
 float n12)

Parameters:

n00 - numbers which define the 4x4 matrix to be multiplied

n01 - numbers which define the 4x4 matrix to be multiplied

n02 - numbers which define the 4x4 matrix to be multiplied

n10 - numbers which define the 4x4 matrix to be multiplied

n11 - numbers which define the 4x4 matrix to be multiplied

n12 - numbers which define the 4x4 matrix to be multiplied

applyMatrix

public void applyMatrix(PMatrix3D source)

applyMatrix

public void applyMatrix(float n00,
 float n01,
 float n02,
 float n03,
 float n10,
 float n11,
 float n12,
 float n13,
 float n20,
 float n21,
 float n22,
 float n23,
 float n30,
 float n31,
 float n32,
 float n33)

Parameters:

n03 - numbers which define the 4x4 matrix to be multiplied

n13 - numbers which define the 4x4 matrix to be multiplied

n20 - numbers which define the 4x4 matrix to be multiplied

n21 - numbers which define the 4x4 matrix to be multiplied

n22 - numbers which define the 4x4 matrix to be multiplied

n23 - numbers which define the 4x4 matrix to be multiplied

n30 - numbers which define the 4x4 matrix to be multiplied

n31 - numbers which define the 4x4 matrix to be multiplied

n32 - numbers which define the 4x4 matrix to be multiplied

n33 - numbers which define the 4x4 matrix to be multiplied

getMatrix

public PMatrix getMatrix()

getMatrix

public PMatrix2D getMatrix(PMatrix2D target)

Copy the current transformation matrix into the specified target. Pass in null to create a new matrix.

getMatrix

public PMatrix3D getMatrix(PMatrix3D target)

Copy the current transformation matrix into the specified target. Pass in null to create a new matrix.

setMatrix

public void setMatrix(PMatrix source)

Set the current transformation matrix to the contents of another.

setMatrix

public void setMatrix(PMatrix2D source)

Set the current transformation to the contents of the specified source.

setMatrix

public void setMatrix(PMatrix3D source)

Set the current transformation to the contents of the specified source.

printMatrix

public void printMatrix()

Prints the current matrix to the Console (the text window at the bottom of Processing).

See Also:

• pushMatrix()
• popMatrix()
• resetMatrix()
• applyMatrix(PMatrix)

beginCamera

public void beginCamera()

The beginCamera() and endCamera() functions enable advanced customization of the camera space. The functions are useful if you want to more control over camera movement, however for most users, the camera() function will be sufficient.

The camera functions will replace any transformations (such as rotate() or translate()) that occur before them in draw(), but they will not automatically replace the camera transform itself. For this reason, camera functions should be placed at the beginning of draw() (so that transformations happen afterwards), and the camera() function can be used after beginCamera() if you want to reset the camera before applying transformations.

This function sets the matrix mode to the camera matrix so calls such as translate(), rotate(), applyMatrix() and resetMatrix() affect the camera. beginCamera() should always be used with a following endCamera() and pairs of beginCamera() and endCamera() cannot be nested.

See Also:

• camera()
• endCamera()
• applyMatrix(PMatrix)
• resetMatrix()
• translate(float, float, float)
• scale(float, float, float)

endCamera

public void endCamera()

The beginCamera() and endCamera() functions enable advanced customization of the camera space. Please see the reference for beginCamera() for a description of how the functions are used.

See Also:

• beginCamera()
• camera(float, float, float, float, float, float, float, float, float)

camera

public void camera()

Sets the position of the camera through setting the eye position, the center of the scene, and which axis is facing upward. Moving the eye position and the direction it is pointing (the center of the scene) allows the images to be seen from different angles. The version without any parameters sets the camera to the default position, pointing to the center of the display window with the Y axis as up. The default values are camera(width/2.0, height/2.0, (height/2.0) / tan(PI*30.0 / 180.0), width/2.0, height/2.0, 0, 0, 1, 0). This function is similar to gluLookAt() in OpenGL, but it first clears the current camera settings.

See Also:

• beginCamera()
• endCamera()
• frustum(float, float, float, float, float, float)

camera

public void camera(float eyeX,
 float eyeY,
 float eyeZ,
 float centerX,
 float centerY,
 float centerZ,
 float upX,
 float upY,
 float upZ)

Parameters:

eyeX - x-coordinate for the eye

eyeY - y-coordinate for the eye

eyeZ - z-coordinate for the eye

centerX - x-coordinate for the center of the scene

centerY - y-coordinate for the center of the scene

centerZ - z-coordinate for the center of the scene

upX - usually 0.0, 1.0, or -1.0

upY - usually 0.0, 1.0, or -1.0

upZ - usually 0.0, 1.0, or -1.0

printCamera

public void printCamera()

Prints the current camera matrix to the Console (the text window at the bottom of Processing).

See Also:

• camera(float, float, float, float, float, float, float, float, float)

ortho

public void ortho()

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).

ortho

public void ortho(float left,
 float right,
 float bottom,
 float top)

Parameters:

left - left plane of the clipping volume

right - right plane of the clipping volume

bottom - bottom plane of the clipping volume

top - top plane of the clipping volume

ortho

public void ortho(float left,
 float right,
 float bottom,
 float top,
 float near,
 float far)

Parameters:

near - maximum distance from the origin to the viewer

far - maximum distance from the origin away from the viewer

perspective

public void perspective()

Sets a perspective projection applying foreshortening, making distant objects appear smaller than closer ones. The parameters define a viewing volume with the shape of truncated pyramid. Objects near to the front of the volume appear their actual size, while farther objects appear smaller. This projection simulates the perspective of the world more accurately than orthographic projection. The version of perspective without parameters sets the default perspective and the version with four parameters allows the programmer to set the area precisely. The default values are: perspective(PI/3.0, width/height, cameraZ/10.0, cameraZ*10.0) where cameraZ is ((height/2.0) / tan(PI*60.0/360.0))

perspective

public void perspective(float fovy,
 float aspect,
 float zNear,
 float zFar)

Parameters:

fovy - field-of-view angle (in radians) for vertical direction

aspect - ratio of width to height

zNear - z-position of nearest clipping plane

zFar - z-position of the farthest clipping plane

frustum

public void frustum(float left,
 float right,
 float bottom,
 float top,
 float near,
 float far)

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.

Parameters:

left - left coordinate of the clipping plane

right - right coordinate of the clipping plane

bottom - bottom coordinate of the clipping plane

top - top coordinate of the clipping plane

near - near component of the clipping plane; must be greater than zero

far - far component of the clipping plane; must be greater than the near value

See Also:

• camera(float, float, float, float, float, float, float, float, float)
• beginCamera()
• endCamera()
• perspective(float, float, float, float)

printProjection

public void printProjection()

Prints the current projection matrix to the Console (the text window at the bottom of Processing).

See Also:

• camera(float, float, float, float, float, float, float, float, float)

screenX

public float screenX(float x,
 float y)

Takes a three-dimensional X, Y, Z position and returns the X value for where it will appear on a (two-dimensional) screen.

Parameters:

x - 3D x-coordinate to be mapped

y - 3D y-coordinate to be mapped

See Also:

• screenY(float, float, float)
• screenZ(float, float, float)

screenY

public float screenY(float x,
 float y)

Takes a three-dimensional X, Y, Z position and returns the Y value for where it will appear on a (two-dimensional) screen.

Parameters:

x - 3D x-coordinate to be mapped

y - 3D y-coordinate to be mapped

See Also:

• screenX(float, float, float)
• screenZ(float, float, float)

screenX

public float screenX(float x,
 float y,
 float z)

Parameters:

z - 3D z-coordinate to be mapped

screenY

public float screenY(float x,
 float y,
 float z)

Parameters:

z - 3D z-coordinate to be mapped

screenZ

public float screenZ(float x,
 float y,
 float z)

Takes a three-dimensional X, Y, Z position and returns the Z value for where it will appear on a (two-dimensional) screen.

Parameters:

x - 3D x-coordinate to be mapped

y - 3D y-coordinate to be mapped

z - 3D z-coordinate to be mapped

See Also:

• screenX(float, float, float)
• screenY(float, float, float)

modelX

public float modelX(float x,
 float y,
 float z)

Returns the three-dimensional X, Y, Z position in model space. This returns the X value for a given coordinate based on the current set of transformations (scale, rotate, translate, etc.) The X value can be used to place an object in space relative to the location of the original point once the transformations are no longer in use.

In the example, the modelX(), modelY(), and modelZ() functions record the location of a box in space after being placed using a series of translate and rotate commands. After popMatrix() is called, those transformations no longer apply, but the (x, y, z) coordinate returned by the model functions is used to place another box in the same location.

Parameters:

x - 3D x-coordinate to be mapped

y - 3D y-coordinate to be mapped

z - 3D z-coordinate to be mapped

See Also:

• modelY(float, float, float)
• modelZ(float, float, float)

modelY

public float modelY(float x,
 float y,
 float z)

Returns the three-dimensional X, Y, Z position in model space. This returns the Y value for a given coordinate based on the current set of transformations (scale, rotate, translate, etc.) The Y value can be used to place an object in space relative to the location of the original point once the transformations are no longer in use.

In the example, the modelX(), modelY(), and modelZ() functions record the location of a box in space after being placed using a series of translate and rotate commands. After popMatrix() is called, those transformations no longer apply, but the (x, y, z) coordinate returned by the model functions is used to place another box in the same location.

Parameters:

x - 3D x-coordinate to be mapped

y - 3D y-coordinate to be mapped

z - 3D z-coordinate to be mapped

See Also:

• modelX(float, float, float)
• modelZ(float, float, float)

modelZ

public float modelZ(float x,
 float y,
 float z)

Returns the three-dimensional X, Y, Z position in model space. This returns the Z value for a given coordinate based on the current set of transformations (scale, rotate, translate, etc.) The Z value can be used to place an object in space relative to the location of the original point once the transformations are no longer in use.

In the example, the modelX(), modelY(), and modelZ() functions record the location of a box in space after being placed using a series of translate and rotate commands. After popMatrix() is called, those transformations no longer apply, but the (x, y, z) coordinate returned by the model functions is used to place another box in the same location.

Parameters:

x - 3D x-coordinate to be mapped

y - 3D y-coordinate to be mapped

z - 3D z-coordinate to be mapped

See Also:

• modelX(float, float, float)
• modelY(float, float, float)

pushStyle

public void pushStyle()

The pushStyle() function saves the current style settings and popStyle() restores the prior settings. Note that these functions are always used together. They allow you to change the style settings and later return to what you had. When a new style is started with pushStyle(), it builds on the current style information. The pushStyle() and popStyle() functions can be embedded to provide more control (see the second example above for a demonstration.)

The style information controlled by the following functions are included in the style: fill(), stroke(), tint(), strokeWeight(), strokeCap(),strokeJoin(), imageMode(), rectMode(), ellipseMode(), shapeMode(), colorMode(), textAlign(), textFont(), textMode(), textSize(), textLeading(), emissive(), specular(), shininess(), ambient()

See Also:

• popStyle()

popStyle

public void popStyle()

The pushStyle() function saves the current style settings and popStyle() restores the prior settings; these functions are always used together. They allow you to change the style settings and later return to what you had. When a new style is started with pushStyle(), it builds on the current style information. The pushStyle() and popStyle() functions can be embedded to provide more control (see the second example above for a demonstration.)

See Also:

• pushStyle()

style

public void style(PStyle s)

getStyle

public PStyle getStyle()

getStyle

public PStyle getStyle(PStyle s)

strokeWeight

public void strokeWeight(float weight)

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().

Parameters:

weight - the weight (in pixels) of the stroke

See Also:

• stroke(int, float)
• strokeJoin(int)
• strokeCap(int)

strokeJoin

public void strokeJoin(int join)

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.

Parameters:

join - either MITER, BEVEL, ROUND

See Also:

• stroke(int, float)
• strokeWeight(float)
• strokeCap(int)

strokeCap

public void strokeCap(int cap)

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.

Parameters:

cap - either SQUARE, PROJECT, or ROUND

See Also:

• stroke(int, float)
• strokeWeight(float)
• strokeJoin(int)
• PApplet.size(int, int, String, String)

noStroke

public void noStroke()

Disables drawing the stroke (outline). If both noStroke() and noFill() are called, nothing will be drawn to the screen.

See Also:

• stroke(int, float)
• fill(float, float, float, float)
• noFill()

stroke

public void stroke(int rgb)

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.

Parameters:

rgb - color value in hexadecimal notation

See Also:

• noStroke()
• strokeWeight(float)
• strokeJoin(int)
• strokeCap(int)
• fill(int, float)
• noFill()
• tint(int, float)
• background(float, float, float, float)
• colorMode(int, float, float, float, float)

stroke

public void stroke(int rgb,
 float alpha)

Parameters:

alpha - opacity of the stroke

stroke

public void stroke(float gray)

Parameters:

gray - specifies a value between white and black

stroke

public void stroke(float gray,
 float alpha)

stroke

public void stroke(float v1,
 float v2,
 float v3)

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

stroke

public void stroke(float v1,
 float v2,
 float v3,
 float alpha)

noTint

public void noTint()

Removes the current fill value for displaying images and reverts to displaying images with their original hues.

See Also:

• tint(float, float, float, float)
• image(PImage, float, float, float, float)

Usage:

web_application

tint

public void tint(int rgb)

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.

Parameters:

rgb - color value in hexadecimal notation

See Also:

• noTint()
• image(PImage, float, float, float, float)

Usage:

web_application

tint

public void tint(int rgb,
 float alpha)

Parameters:

alpha - opacity of the image

tint

public void tint(float gray)

Parameters:

gray - specifies a value between white and black

tint

public void tint(float gray,
 float alpha)

tint

public void tint(float v1,
 float v2,
 float v3)

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

tint

public void tint(float v1,
 float v2,
 float v3,
 float alpha)

noFill

public void noFill()

Disables filling geometry. If both noStroke() and noFill() are called, nothing will be drawn to the screen.

See Also:

• fill(float, float, float, float)
• stroke(int, float)
• noStroke()

Usage:

web_application

fill

public void fill(int rgb)

Sets the color used to fill shapes. For example, if you run fill(204, 102, 0), all subsequent shapes will be filled with orange. 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.

To change the color of an image (or a texture), use tint().

Parameters:

rgb - color variable or hex value

See Also:

• noFill()
• stroke(int, float)
• noStroke()
• tint(int, float)
• background(float, float, float, float)
• colorMode(int, float, float, float, float)

Usage:

web_application

fill

public void fill(int rgb,
 float alpha)

Parameters:

alpha - opacity of the fill

fill

public void fill(float gray)

Parameters:

gray - number specifying value between white and black

fill

public void fill(float gray,
 float alpha)

fill

public void fill(float v1,
 float v2,
 float v3)

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

fill

public void fill(float v1,
 float v2,
 float v3,
 float alpha)

ambient

public void ambient(int rgb)

Sets the ambient reflectance for shapes drawn to the screen. This is combined with the ambient light component of environment. The color components set through the parameters define the reflectance. For example in the default color mode, setting v1=255, v2=126, v3=0, would cause all the red light to reflect and half of the green light to reflect. Used in combination with emissive(), specular(), and shininess() in setting the material properties of shapes.

Parameters:

rgb - any value of the color datatype

See Also:

• emissive(float, float, float)
• specular(float, float, float)
• shininess(float)

Usage:

web_application

ambient

public void ambient(float gray)

Parameters:

gray - number specifying value between white and black

ambient

public void ambient(float v1,
 float v2,
 float v3)

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

specular

public void specular(int rgb)

Sets the specular color of the materials used for shapes drawn to the screen, which sets the color of highlights. Specular refers to light which bounces off a surface in a preferred direction (rather than bouncing in all directions like a diffuse light). Used in combination with emissive(), ambient(), and shininess() in setting the material properties of shapes.

Parameters:

rgb - color to set

See Also:

• lightSpecular(float, float, float)
• ambient(float, float, float)
• emissive(float, float, float)
• shininess(float)

Usage:

web_application

specular

public void specular(float gray)

gray number specifying value between white and black

Parameters:

gray - value between black and white, by default 0 to 255

specular

public void specular(float v1,
 float v2,
 float v3)

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

shininess

public void shininess(float shine)

Sets the amount of gloss in the surface of shapes. Used in combination with ambient(), specular(), and emissive() in setting the material properties of shapes.

Parameters:

shine - degree of shininess

See Also:

• emissive(float, float, float)
• ambient(float, float, float)
• specular(float, float, float)

Usage:

web_application

emissive

public void emissive(int rgb)

Sets the emissive color of the material used for drawing shapes drawn to the screen. Used in combination with ambient(), specular(), and shininess() in setting the material properties of shapes.

Parameters:

rgb - color to set

See Also:

• ambient(float, float, float)
• specular(float, float, float)
• shininess(float)

Usage:

web_application

emissive

public void emissive(float gray)

gray number specifying value between white and black

Parameters:

gray - value between black and white, by default 0 to 255

emissive

public void emissive(float v1,
 float v2,
 float v3)

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

lights

public void lights()

Sets the default ambient light, directional light, falloff, and specular values. The defaults are ambientLight(128, 128, 128) and directionalLight(128, 128, 128, 0, 0, -1), lightFalloff(1, 0, 0), and lightSpecular(0, 0, 0). 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.

See Also:

• ambientLight(float, float, float, float, float, float)
• directionalLight(float, float, float, float, float, float)
• pointLight(float, float, float, float, float, float)
• spotLight(float, float, float, float, float, float, float, float, float, float, float)
• noLights()

Usage:

web_application

noLights

public void noLights()

Disable all lighting. Lighting is turned off by default and enabled with the lights() function. This function can be used to disable lighting so that 2D geometry (which does not require lighting) can be drawn after a set of lighted 3D geometry.

See Also:

• lights()

Usage:

web_application

ambientLight

public void ambientLight(float v1,
 float v2,
 float v3)

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.

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

See Also:

• lights()
• directionalLight(float, float, float, float, float, float)
• pointLight(float, float, float, float, float, float)
• spotLight(float, float, float, float, float, float, float, float, float, float, float)

Usage:

web_application

ambientLight

public void ambientLight(float v1,
 float v2,
 float v3,
 float x,
 float y,
 float z)

Parameters:

x - x-coordinate of the light

y - y-coordinate of the light

z - z-coordinate of the light

directionalLight

public void directionalLight(float v1,
 float v2,
 float v3,
 float nx,
 float ny,
 float nz)

Adds a directional light. Directional light comes from one direction and is stronger when hitting a surface squarely and weaker if it hits at a gentle angle. After hitting a surface, a directional lights scatters in all directions. 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 nx, ny, and nz parameters specify the direction the light is facing. For example, setting ny to -1 will cause the geometry to be lit from below (the light is facing directly upward).

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

nx - direction along the x-axis

ny - direction along the y-axis

nz - direction along the z-axis

See Also:

• lights()
• ambientLight(float, float, float, float, float, float)
• pointLight(float, float, float, float, float, float)
• spotLight(float, float, float, float, float, float, float, float, float, float, float)

Usage:

web_application

pointLight

public void pointLight(float v1,
 float v2,
 float v3,
 float x,
 float y,
 float z)

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.

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

x - x-coordinate of the light

y - y-coordinate of the light

z - z-coordinate of the light

See Also:

• lights()
• directionalLight(float, float, float, float, float, float)
• ambientLight(float, float, float, float, float, float)
• spotLight(float, float, float, float, float, float, float, float, float, float, float)

Usage:

web_application

spotLight

public void spotLight(float v1,
 float v2,
 float v3,
 float x,
 float y,
 float z,
 float nx,
 float ny,
 float nz,
 float angle,
 float concentration)

Adds a spotlight. 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.

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

x - x-coordinate of the light

y - y-coordinate of the light

z - z-coordinate of the light

nx - direction along the x-axis

ny - direction along the y-axis

nz - direction along the z-axis

angle - angle of the spotlight cone

concentration - exponent determining the center bias of the cone

See Also:

• lights()
• directionalLight(float, float, float, float, float, float)
• pointLight(float, float, float, float, float, float)
• ambientLight(float, float, float, float, float, float)

Usage:

web_application

lightFalloff

public void lightFalloff(float constant,
 float linear,
 float quadratic)

Sets the falloff rates for point lights, spotlights, 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 ambient lit with one color and another region to be ambient lit 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.

Parameters:

constant - constant value or determining falloff

linear - linear value for determining falloff

quadratic - quadratic value for determining falloff

See Also:

• lights()
• ambientLight(float, float, float, float, float, float)
• pointLight(float, float, float, float, float, float)
• spotLight(float, float, float, float, float, float, float, float, float, float, float)
• lightSpecular(float, float, float)

Usage:

web_application

lightSpecular

public void lightSpecular(float v1,
 float v2,
 float v3)

Sets the specular color for lights. Like fill(), it affects only the elements which are created after it in the code. Specular refers to light which bounces off a surface in a preferred direction (rather than bouncing in all directions like a diffuse light) and is used for creating highlights. The specular quality of a light interacts with the specular material qualities set through the specular() and shininess() functions.

Parameters:

v1 - red or hue value (depending on current color mode)

v2 - green or saturation value (depending on current color mode)

v3 - blue or brightness value (depending on current color mode)

See Also:

• specular(float, float, float)
• lights()
• ambientLight(float, float, float, float, float, float)
• pointLight(float, float, float, float, float, float)
• spotLight(float, float, float, float, float, float, float, float, float, float, float)

Usage:

web_application

background

public void background(int rgb)

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 background 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.

Parameters:

rgb - any value of the color datatype

See Also:

• stroke(float)
• fill(float)
• tint(float)
• colorMode(int)

Usage:

web_application

background

public void background(int rgb,
 float alpha)

Parameters:

alpha - opacity of the background

background

public void background(float gray)

Parameters:

gray - specifies a value between white and black

background

public void background(float gray,
 float alpha)

background

public void background(float v1,
 float v2,
 float v3)

Parameters:

v1 - red or hue value (depending on the current color mode)

v2 - green or saturation value (depending on the current color mode)

v3 - blue or brightness value (depending on the current color mode)

background

public void background(float v1,
 float v2,
 float v3,
 float alpha)

clear

public void clear()

Clears the pixels within a buffer. This function only works on PGraphics objects created with the createGraphics() function. Unlike the main graphics context (the display window), pixels in additional graphics areas created with createGraphics() can be entirely or partially transparent. This function clears everything in a PGraphics object to make all the pixels 100% transparent.

background

public void background(PImage image)

Takes an RGB or ARGB image and sets it as the background. The width and height of the image must be the same size as the sketch. Use image.resize(width, height) to make short work of such a task.

Note that even if the image is set as RGB, the high 8 bits of each pixel should be set opaque (0xFF000000) because the image data will be copied directly to the screen, and non-opaque background images may have strange behavior. Use image.filter(OPAQUE) to handle this easily.

When using 3D, this will also clear the zbuffer (if it exists).

Parameters:

image - PImage to set as background (must be same size as the sketch window)

colorMode

public void colorMode(int 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 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).

Parameters:

mode - Either RGB or HSB, corresponding to Red/Green/Blue and Hue/Saturation/Brightness

See Also:

• background(float)
• fill(float)
• stroke(float)

Usage:

web_application

colorMode

public void colorMode(int mode,
 float max)

Parameters:

max - range for all color elements

colorMode

public void colorMode(int mode,
 float max1,
 float max2,
 float max3)

Parameters:

max1 - range for the red or hue depending on the current color mode

max2 - range for the green or saturation depending on the current color mode

max3 - range for the blue or brightness depending on the current color mode

colorMode

public void colorMode(int mode,
 float max1,
 float max2,
 float max3,
 float maxA)

Parameters:

maxA - range for the alpha

color

public final int color(int c)

color

public final int color(float gray)

color

public final int color(int c,
 int alpha)

Parameters:

c - can be packed ARGB or a gray in this case

color

public final int color(int c,
 float alpha)

Parameters:

c - can be packed ARGB or a gray in this case

color

public final int color(float gray,
 float alpha)

color

public final int color(int v1,
 int v2,
 int v3)

color

public final int color(float v1,
 float v2,
 float v3)

color

public final int color(int v1,
 int v2,
 int v3,
 int a)

color

public final int color(float v1,
 float v2,
 float v3,
 float a)

alpha

public final float alpha(int rgb)

Extracts the alpha value from a color.

Parameters:

rgb - any value of the color datatype

See Also:

• red(int)
• green(int)
• blue(int)
• hue(int)
• saturation(int)
• brightness(int)

Usage:

web_application

red

public final float red(int rgb)

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 achieve 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
 

Parameters:

rgb - any value of the color datatype

See Also:

• green(int)
• blue(int)
• alpha(int)
• hue(int)
• saturation(int)
• brightness(int)

Usage:

web_application

green

public final float green(int rgb)

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 achieve 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
 

Parameters:

rgb - any value of the color datatype

See Also:

• red(int)
• blue(int)
• alpha(int)
• hue(int)
• saturation(int)
• brightness(int)

Usage:

web_application

blue

public final float blue(int rgb)

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 achieve 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
 

Parameters:

rgb - any value of the color datatype

See Also:

• red(int)
• green(int)
• alpha(int)
• hue(int)
• saturation(int)
• brightness(int)

Usage:

web_application

hue

public final float hue(int rgb)

Extracts the hue value from a color.

Parameters:

rgb - any value of the color datatype

See Also:

• red(int)
• green(int)
• blue(int)
• alpha(int)
• saturation(int)
• brightness(int)

Usage:

web_application

saturation

public final float saturation(int rgb)

Extracts the saturation value from a color.

Parameters:

rgb - any value of the color datatype

See Also:

• red(int)
• green(int)
• blue(int)
• alpha(int)
• hue(int)
• brightness(int)

Usage:

web_application

brightness

public final float brightness(int rgb)

Extracts the brightness value from a color.

Parameters:

rgb - any value of the color datatype

See Also:

• red(int)
• green(int)
• blue(int)
• alpha(int)
• hue(int)
• saturation(int)

Usage:

web_application

lerpColor

public int lerpColor(int c1,
 int c2,
 float amt)

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.

Parameters:

c1 - interpolate from this color

c2 - interpolate to this color

amt - between 0.0 and 1.0

See Also:

• PImage.blendColor(int, int, int)
• color(float, float, float, float)
• PApplet.lerp(float, float, float)

Usage:

web_application

lerpColor

public static int lerpColor(int c1,
 int c2,
 float amt,
 int mode)

beginRaw

public void beginRaw(PGraphics rawGraphics)

Record individual lines and triangles by echoing them to another renderer.

endRaw

public void endRaw()

haveRaw

public boolean haveRaw()

getRaw

public PGraphics getRaw()

showWarning

public static void showWarning(String msg)

Show a renderer error, and keep track of it so that it's only shown once.

Parameters:

msg - the error message (which will be stored for later comparison)

showWarning

public static void showWarning(String msg,
 Object... args)

Version of showWarning() that takes a parsed String.

showDepthWarning

public static void showDepthWarning(String method)

Display a warning that the specified method is only available with 3D.

Parameters:

method - The method name (no parentheses)

showDepthWarningXYZ

public static void showDepthWarningXYZ(String method)

Display a warning that the specified method that takes x, y, z parameters can only be used with x and y parameters in this renderer.

Parameters:

method - The method name (no parentheses)

showMethodWarning

public static void showMethodWarning(String method)

Display a warning that the specified method is simply unavailable.

showVariationWarning

public static void showVariationWarning(String str)

Error that a particular variation of a method is unavailable (even though other variations are). For instance, if vertex(x, y, u, v) is not available, but vertex(x, y) is just fine.

showMissingWarning

public static void showMissingWarning(String method)

Display a warning that the specified method is not implemented, meaning that it could be either a completely missing function, although other variations of it may still work properly.

showException

public static void showException(String msg)

Show a renderer-related exception that halts the program. Currently just wraps the message as a RuntimeException and throws it, but might do something more specific might be used in the future.

displayable

public boolean displayable()

Return true if this renderer should be drawn to the screen. Defaults to returning true, since nearly all renderers are on-screen beasts. But can be overridden for subclasses like PDF so that a window doesn't open up.

A better name? showFrame, displayable, isVisible, visible, shouldDisplay, what to call this?

is2D

public boolean is2D()

Return true if this renderer supports 2D drawing. Defaults to true.

is3D

public boolean is3D()

Return true if this renderer supports 3D drawing. Defaults to false.

isGL

public boolean isGL()

Return true if this renderer uses OpenGL. Defaults to false.

is2X

public boolean is2X()

save

public boolean save(String filename)

Description copied from class: PImage

Saves the image into a file. 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.

To save an image created within the code, rather than through loading, it's necessary to make the image with the createImage() function, so it is aware of the location of the program and can therefore save the file to the right place. See the createImage() reference for more information.

Advanced

Save this image to disk.

As of revision 0100, this function requires an absolute path, in order to avoid confusion. To save inside the sketch folder, use the function savePath() from PApplet, or use saveFrame() instead. As of revision 0116, savePath() is not needed if this object has been created (as recommended) via createImage() or createGraphics() or one of its neighbors.

As of revision 0115, when using Java 1.4 and later, you can write to several formats besides tga and tiff. If Java 1.4 is installed and the extension used is supported (usually png, jpg, jpeg, bmp, and tiff), then those methods will be used to write the image. To get a list of the supported formats for writing, use:
println(javax.imageio.ImageIO.getReaderFormatNames())

In Processing 4.0 beta 5, the old (and sometimes buggy) TIFF reader/writer was removed, so ImageIO is used for TIFF files.

Also, files must have an extension: we're no longer adding .tif to files with no extension, because that can lead to confusing results, and the behavior is inconsistent with the rest of the API.

Overrides:

save in class PImage

Parameters:

filename - a sequence of letters and numbers