Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

processing.core
Class PGraphics3D

java.lang.Object
  extended by processing.core.PImage
      extended by processing.core.PGraphics
          extended by processing.core.PGraphics3D
All Implemented Interfaces:
java.lang.Cloneable, PConstants
Direct Known Subclasses:
PGraphicsOpenGL, RawDXF
public class PGraphics3D
extends PGraphics

Subclass of PGraphics that handles 3D rendering. It can render 3D inside a browser window and requires no plug-ins.

The renderer is mostly set up based on the structure of the OpenGL API, if you have questions about specifics that aren't covered here, look for reference on the OpenGL implementation of a similar feature.

Lighting and camera implementation by Simon Greenwold.

Field Summary
 PMatrix3D camera
          The camera matrix, the modelview will be set to this on beginDraw.
 float cameraAspect
          Aspect ratio of camera's view.
 float cameraFar
           
 float cameraFOV
          Camera field of view.
 float cameraNear
           
 float cameraX
          Position of the camera.
 float cameraY
          Position of the camera.
 float cameraZ
          Position of the camera.
 float currentLightFalloffConstant
          Current light falloff
 float currentLightFalloffLinear
           
 float currentLightFalloffQuadratic
           
 float[] currentLightSpecular
          Current specular color for lighting
 int lightCount
           
 float[][] lightDiffuse
          Diffuse colors for lights.
 float[] lightFalloffConstant
          Light falloff
 float[] lightFalloffLinear
           
 float[] lightFalloffQuadratic
           
 PVector[] lightNormal
          Light direction (normalized vector)
 PVector[] lightPosition
          Light positions
 float[][] lightSpecular
          Specular colors for lights.
 float[] lightSpotAngle
          Light spot angle
 float[] lightSpotAngleCos
          Cosine of light spot angle
 float[] lightSpotConcentration
          Light spot concentration
 int[] lightType
          Light types
 PLine line
           
static int MAX_LIGHTS
          Maximum lights by default is 8, which is arbitrary for this renderer, but is the minimum defined by OpenGL
 PMatrix3D modelview
          The modelview matrix.
 PMatrix3D modelviewInv
          Inverse modelview matrix, used for lighting.
 PMatrix3D projection
          Current projection matrix.
 PSmoothTriangle smoothTriangle
          Used for anti-aliased and perspective corrected rendering.
static int TRI_COLOR_COUNT
           
static int TRI_DIFFUSE_A
           
static int TRI_DIFFUSE_B
           
static int TRI_DIFFUSE_G
           
static int TRI_DIFFUSE_R
           
static int TRI_SPECULAR_B
           
static int TRI_SPECULAR_G
           
static int TRI_SPECULAR_R
           
 PTriangle triangle
           
 float[] zbuffer
          The depth buffer.
 
Fields inherited from class processing.core.PGraphics
ambientB, ambientG, ambientR, backgroundColor, bezierDetail, colorMode, colorModeA, colorModeX, colorModeY, colorModeZ, curveTightness, edge, ellipseMode, emissiveB, emissiveG, emissiveR, fill, fillColor, image, imageMode, normalX, normalY, normalZ, pixelCount, rectMode, shapeMode, shininess, smooth, specularB, specularG, specularR, sphereDetailU, sphereDetailV, stroke, strokeCap, strokeColor, strokeJoin, strokeWeight, textAlign, textAlignY, textFont, textLeading, textMode, textSize, textureImage, textureMode, textureU, textureV, tint, tintColor
 
Fields inherited from class processing.core.PImage
format, height, parent, pixels, width
 
Fields inherited from interface processing.core.PConstants
A, AB, ADD, AG, ALPHA, ALPHA_MASK, ALT, AMBIENT, AR, ARC, ARGB, ARROW, B, BACKSPACE, BASELINE, BEEN_LIT, BEVEL, BLEND, BLUE_MASK, BLUR, BOTTOM, BOX, BURN, CENTER, CENTER_DIAMETER, CENTER_RADIUS, CHATTER, CLOSE, CMYK, CODED, COMPLAINT, CONTROL, CORNER, CORNERS, CROSS, CUSTOM, DA, DARKEST, DB, DEG_TO_RAD, DELETE, DG, DIAMETER, DIFFERENCE, DILATE, DIRECTIONAL, DISABLE_ACCURATE_TEXTURES, DISABLE_DEPTH_SORT, DISABLE_DEPTH_TEST, DISABLE_OPENGL_2X_SMOOTH, DISABLE_OPENGL_ERROR_REPORT, DODGE, DOWN, DR, DXF, EB, EDGE, EG, ELLIPSE, ENABLE_ACCURATE_TEXTURES, ENABLE_DEPTH_SORT, ENABLE_DEPTH_TEST, ENABLE_NATIVE_FONTS, ENABLE_OPENGL_2X_SMOOTH, ENABLE_OPENGL_4X_SMOOTH, ENABLE_OPENGL_ERROR_REPORT, ENTER, EPSILON, ER, ERODE, ERROR_BACKGROUND_IMAGE_FORMAT, ERROR_BACKGROUND_IMAGE_SIZE, ERROR_PUSHMATRIX_OVERFLOW, ERROR_PUSHMATRIX_UNDERFLOW, ERROR_TEXTFONT_NULL_PFONT, ESC, EXCLUSION, G, GIF, GRAY, GREEN_MASK, HALF_PI, HAND, HARD_LIGHT, HINT_COUNT, HSB, IMAGE, INVERT, JAVA2D, JPEG, LEFT, LIGHTEST, LINE, LINES, LINUX, MACOSX, MAX_FLOAT, MAX_INT, MIN_FLOAT, MIN_INT, MITER, MODEL, MOVE, MULTIPLY, NORMAL, NORMALIZED, NX, NY, NZ, OPAQUE, OPEN, OPENGL, ORTHOGRAPHIC, OTHER, OVERLAY, P2D, P3D, PATH, PDF, PERSPECTIVE, PI, platformNames, POINT, POINTS, POLYGON, POSTERIZE, PROBLEM, PROJECT, QUAD, QUAD_STRIP, QUADS, QUARTER_PI, R, RAD_TO_DEG, RADIUS, RECT, RED_MASK, REPLACE, RETURN, RGB, RIGHT, ROUND, SA, SB, SCREEN, SG, SHAPE, SHIFT, SHINE, SOFT_LIGHT, SPB, SPG, SPHERE, SPOT, SPR, SQUARE, SR, SUBTRACT, SW, TAB, TARGA, TEXT, THIRD_PI, THRESHOLD, TIFF, TOP, TRIANGLE, TRIANGLE_FAN, TRIANGLE_STRIP, TRIANGLES, TWO_PI, TX, TY, TZ, U, UP, V, VERTEX_FIELD_COUNT, VW, VX, VY, VZ, WAIT, WHITESPACE, WINDOWS, X, Y, Z
 
Constructor Summary
PGraphics3D()
           
 
Method Summary
 void ambientLight(float r, float g, float b)
          Add an ambient light based on the current color mode.
 void ambientLight(float r, float g, float b, float x, float y, float z)
          Add an ambient light based on the current color mode.
 void applyMatrix(float n00, float n01, float n02, float n10, float n11, float n12)
          Apply a 3x2 affine transformation matrix.
 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)
          Apply a 4x4 transformation matrix.
 void applyMatrix(PMatrix2D source)
           
 void applyMatrix(PMatrix3D source)
           
 void beginCamera()
          Set matrix mode to the camera matrix (instead of the current transformation matrix).
 void beginDraw()
          Prepares the PGraphics for drawing.
 void beginShape(int kind)
          Start a new shape.
 void box(float w, float h, float d)
           
 void camera()
          Set camera to the default settings.
 void camera(float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ)
          More flexible method for dealing with camera().
 void directionalLight(float r, float g, float b, float nx, float ny, float nz)
           
 void endCamera()
          Record the current settings into the camera matrix, and set the matrix mode back to the current transformation matrix.
 void endDraw()
          See notes in PGraphics.
 void endShape(int mode)
           
 void flush()
          Emit any sorted geometry that's been collected on this frame.
 void frustum(float left, float right, float bottom, float top, float znear, float zfar)
          Same as glFrustum(), except that it wipes out (rather than multiplies against) the current perspective matrix.
 PMatrix getMatrix()
           
 PMatrix3D getMatrix(PMatrix3D target)
          Copy the current transformation matrix into the specified target.
 void hint(int which)
          Enable a hint option.
 boolean is2D()
          Return true if this renderer supports 2D drawing.
 boolean is3D()
          Return true if this renderer supports 2D drawing.
 void lightFalloff(float constant, float linear, float quadratic)
          Set the light falloff rates for the last light that was created.
 void lights()
          Sets up an ambient and directional light.
 void lightSpecular(float x, float y, float z)
          Set the specular color of the last light created.
 float modelX(float x, float y, float z)
          Returns the model space x value for an x, y, z coordinate.
 float modelY(float x, float y, float z)
          Returns the model space y value for an x, y, z coordinate.
 float modelZ(float x, float y, float z)
          Returns the model space z value for an x, y, z coordinate.
 void noLights()
          Turn off all lights.
 void noSmooth()
          Disable smoothing.
 void ortho()
          Calls ortho() with the proper parameters for Processing's standard orthographic projection.
 void ortho(float left, float right, float bottom, float top, float near, float far)
          Similar to gluOrtho(), but wipes out the current projection matrix.
 void perspective()
          Calls perspective() with Processing's standard coordinate projection.
 void perspective(float fov, float aspect, float zNear, float zFar)
          Similar to gluPerspective().
 void pointLight(float r, float g, float b, float x, float y, float z)
           
 void popMatrix()
          Replace the current transformation matrix with the top of the stack.
 void printCamera()
          Print the current camera matrix.
 void printMatrix()
          Print the current model (or "transformation") matrix.
 void printProjection()
          Print the current projection matrix.
 void pushMatrix()
          Push a copy of the current transformation matrix onto the stack.
 void resetMatrix()
          Set the current transformation matrix to identity.
 void rotate(float angle)
          Two dimensional rotation.
 void rotate(float angle, float v0, float v1, float v2)
          Rotate around an arbitrary vector, similar to glRotate(), except that it takes radians (instead of degrees).
 void rotateX(float angle)
          Rotate around the X axis.
 void rotateY(float angle)
          Rotate around the Y axis.
 void rotateZ(float angle)
          Rotate around the Z axis.
 void scale(float s)
          Same as scale(s, s, s).
 void scale(float sx, float sy)
          Same as scale(sx, sy, 1).
 void scale(float x, float y, float z)
          Scale in three dimensions.
 float screenX(float x, float y)
          Given an x and y coordinate, returns the x position of where that point would be placed on screen, once affected by translate(), scale(), or any other transformations.
 float screenX(float x, float y, float z)
          Maps a three dimensional point to its placement on-screen.
 float screenY(float x, float y)
          Given an x and y coordinate, returns the y position of where that point would be placed on screen, once affected by translate(), scale(), or any other transformations.
 float screenY(float x, float y, float z)
          Maps a three dimensional point to its placement on-screen.
 float screenZ(float x, float y, float z)
          Maps a three dimensional point to its placement on-screen.
 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 setSize(int iwidth, int iheight)
          Called in response to a resize event, handles setting the new width and height internally, as well as re-allocating the pixel buffer for the new size.
 void smooth()
          If true in PImage, use bilinear interpolation for copy() operations.
 void sphere(float r)
          Draw a sphere with radius r centered at coordinate 0, 0, 0.
 void spotLight(float r, float g, float b, float x, float y, float z, float nx, float ny, float nz, float angle, float concentration)
           
 void strokeCap(int cap)
           
 void strokeJoin(int join)
           
 void texture(PImage image)
          Set texture image for current shape.
 void translate(float tx, float ty)
          Translate in X and Y.
 void translate(float tx, float ty, float tz)
          Translate in X, Y, and Z.
 void vertex(float x, float y)
           
 void vertex(float x, float y, float u, float v)
           
 
Methods inherited from class processing.core.PGraphics
alpha, ambient, ambient, ambient, applyMatrix, arc, background, background, background, background, background, background, background, beginRaw, beginShape, bezier, bezier, bezierDetail, bezierPoint, bezierTangent, bezierVertex, bezierVertex, blue, box, breakShape, brightness, canDraw, color, color, color, color, color, color, color, color, color, colorMode, colorMode, colorMode, colorMode, curve, curve, curveDetail, curvePoint, curveTangent, curveTightness, curveVertex, curveVertex, displayable, dispose, edge, ellipse, ellipseMode, emissive, emissive, emissive, endRaw, endShape, fill, fill, fill, fill, fill, fill, getMatrix, getStyle, getStyle, green, hue, image, image, image, imageMode, lerpColor, lerpColor, line, line, noFill, normal, noStroke, noTint, point, point, popStyle, pushStyle, quad, rect, rectMode, red, saturation, setMatrix, setParent, setPath, setPrimary, shape, shape, shape, shapeMode, shininess, showException, showWarning, specular, specular, specular, sphereDetail, sphereDetail, stroke, stroke, stroke, stroke, stroke, stroke, strokeWeight, style, text, text, text, text, text, text, text, text, text, text, text, text, text, text, textAlign, textAlign, textAscent, textDescent, textFont, textFont, textLeading, textMode, textSize, textureMode, textWidth, textWidth, tint, tint, tint, tint, tint, tint, triangle, vertex, vertex, vertex
 
Methods inherited from class processing.core.PImage
blend, blend, blendColor, clone, copy, copy, filter, filter, get, get, get, getCache, getImage, init, isModified, loadPixels, mask, mask, removeCache, resize, save, set, set, setCache, setModified, setModified, updatePixels, updatePixels
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

zbuffer

public float[] zbuffer
The depth buffer.

modelview

public PMatrix3D modelview
The modelview matrix.

modelviewInv

public PMatrix3D modelviewInv
Inverse modelview matrix, used for lighting.

camera

public PMatrix3D camera
The camera matrix, the modelview will be set to this on beginDraw.

cameraFOV

public float cameraFOV
Camera field of view.

cameraX

public float cameraX
Position of the camera.

cameraY

public float cameraY
Position of the camera.

cameraZ

public float cameraZ
Position of the camera.

cameraNear

public float cameraNear

cameraFar

public float cameraFar

cameraAspect

public float cameraAspect
Aspect ratio of camera's view.

projection

public PMatrix3D projection
Current projection matrix.

MAX_LIGHTS

public static final int MAX_LIGHTS
Maximum lights by default is 8, which is arbitrary for this renderer, but is the minimum defined by OpenGL

See Also:
Constant Field Values

lightCount

public int lightCount

lightType

public int[] lightType
Light types

lightPosition

public PVector[] lightPosition
Light positions

lightNormal

public PVector[] lightNormal
Light direction (normalized vector)

lightFalloffConstant

public float[] lightFalloffConstant
Light falloff

lightFalloffLinear

public float[] lightFalloffLinear

lightFalloffQuadratic

public float[] lightFalloffQuadratic

lightSpotAngle

public float[] lightSpotAngle
Light spot angle

lightSpotAngleCos

public float[] lightSpotAngleCos
Cosine of light spot angle

lightSpotConcentration

public float[] lightSpotConcentration
Light spot concentration

lightDiffuse

public float[][] lightDiffuse
Diffuse colors for lights. For an ambient light, this will hold the ambient color. Internally these are stored as numbers between 0 and 1.

lightSpecular

public float[][] lightSpecular
Specular colors for lights. Internally these are stored as numbers between 0 and 1.

currentLightSpecular

public float[] currentLightSpecular
Current specular color for lighting

currentLightFalloffConstant

public float currentLightFalloffConstant
Current light falloff

currentLightFalloffLinear

public float currentLightFalloffLinear

currentLightFalloffQuadratic

public float currentLightFalloffQuadratic

TRI_DIFFUSE_R

public static final int TRI_DIFFUSE_R
See Also:
Constant Field Values

TRI_DIFFUSE_G

public static final int TRI_DIFFUSE_G
See Also:
Constant Field Values

TRI_DIFFUSE_B

public static final int TRI_DIFFUSE_B
See Also:
Constant Field Values

TRI_DIFFUSE_A

public static final int TRI_DIFFUSE_A
See Also:
Constant Field Values

TRI_SPECULAR_R

public static final int TRI_SPECULAR_R
See Also:
Constant Field Values

TRI_SPECULAR_G

public static final int TRI_SPECULAR_G
See Also:
Constant Field Values

TRI_SPECULAR_B

public static final int TRI_SPECULAR_B
See Also:
Constant Field Values

TRI_COLOR_COUNT

public static final int TRI_COLOR_COUNT
See Also:
Constant Field Values

smoothTriangle

public PSmoothTriangle smoothTriangle
Used for anti-aliased and perspective corrected rendering.

line

public PLine line

triangle

public PTriangle triangle
Constructor Detail

PGraphics3D

public PGraphics3D()
Method Detail

setSize

public void setSize(int iwidth,
                    int iheight)
Called in response to a resize event, handles setting the new width and height internally, as well as re-allocating the pixel buffer for the new size. Note that this will nuke any cameraMode() settings.

Overrides:
setSize in class PGraphics

beginDraw

public void beginDraw()
Description copied from class: PGraphics
Prepares the PGraphics for drawing.

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

Overrides:
beginDraw in class PGraphics

endDraw

public void endDraw()
See notes in PGraphics. If z-sorting has been turned on, then the triangles will all be quicksorted here (to make alpha work more properly) and then blit to the screen.

Overrides:
endDraw in class PGraphics

hint

public void hint(int which)
Description copied from class: PGraphics
Enable a hint option.

For the most part, hints are temporary api quirks, for which a proper api hasn't been properly worked out. for instance SMOOTH_IMAGES existed because smooth() wasn't yet implemented, but it will soon go away.

They also exist for obscure features in the graphics engine, like enabling/disabling single pixel lines that ignore the zbuffer, the way they do in alphabot.

Current hint options:

Overrides:
hint in class PGraphics

beginShape

public void beginShape(int kind)
Description copied from class: PGraphics
Start a new shape.

Differences between beginShape() and line() and point() methods.

beginShape() is intended to be more flexible at the expense of being a little more complicated to use. it handles more complicated shapes that can consist of many connected lines (so you get joins) or lines mixed with curves.

The line() and point() command are for the far more common cases (particularly for our audience) that simply need to draw a line or a point on the screen.

From the code side of things, line() may or may not call beginShape() to do the drawing. In the beta code, they do, but in the alpha code, they did not. they might be implemented one way or the other depending on tradeoffs of runtime efficiency vs. implementation efficiency &mdash meaning the speed that things run at vs. the speed it takes me to write the code and maintain it. for beta, the latter is most important so that's how things are implemented.

Overrides:
beginShape in class PGraphics

texture

public void texture(PImage image)
Description copied from class: PGraphics
Set texture image for current shape. Needs to be called between @see beginShape and @see endShape

Overrides:
texture in class PGraphics
Parameters:
image - reference to a PImage object

vertex

public void vertex(float x,
                   float y)
Overrides:
vertex in class PGraphics

vertex

public void vertex(float x,
                   float y,
                   float u,
                   float v)
Overrides:
vertex in class PGraphics

endShape

public void endShape(int mode)
Overrides:
endShape in class PGraphics

flush

public void flush()
Emit any sorted geometry that's been collected on this frame.

Overrides:
flush in class PGraphics

box

public void box(float w,
                float h,
                float d)
Overrides:
box in class PGraphics

sphere

public void sphere(float r)
Description copied from class: PGraphics
Draw a sphere with radius r centered at coordinate 0, 0, 0.

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, er.. 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 modulos)
 and introduced sphereAt(x,y,z,r)
 to avoid additional translate()'s on the user/sketch side

 [davbol 080801] now using separate sphereDetailU/V

Overrides:
sphere in class PGraphics

smooth

public void smooth()
Description copied from class: PGraphics
If true in PImage, use bilinear interpolation for copy() operations. When inherited by PGraphics, also controls shapes.

Overrides:
smooth in class PGraphics

noSmooth

public void noSmooth()
Description copied from class: PGraphics
Disable smoothing. See smooth().

Overrides:
noSmooth in class PGraphics

pushMatrix

public void pushMatrix()
Description copied from class: PGraphics
Push a copy of the current transformation matrix onto the stack.

Overrides:
pushMatrix in class PGraphics

popMatrix

public void popMatrix()
Description copied from class: PGraphics
Replace the current transformation matrix with the top of the stack.

Overrides:
popMatrix in class PGraphics

translate

public void translate(float tx,
                      float ty)
Description copied from class: PGraphics
Translate in X and Y.

Overrides:
translate in class PGraphics

translate

public void translate(float tx,
                      float ty,
                      float tz)
Description copied from class: PGraphics
Translate in X, Y, and Z.

Overrides:
translate in class PGraphics

rotate

public void rotate(float angle)
Two dimensional rotation. Same as rotateZ (this is identical to a 3D rotation along the z-axis) but included for clarity -- it'd be weird for people drawing 2D graphics to be using rotateZ. And they might kick our a-- for the confusion.

Overrides:
rotate in class PGraphics

rotateX

public void rotateX(float angle)
Description copied from class: PGraphics
Rotate around the X axis.

Overrides:
rotateX in class PGraphics

rotateY

public void rotateY(float angle)
Description copied from class: PGraphics
Rotate around the Y axis.

Overrides:
rotateY in class PGraphics

rotateZ

public void rotateZ(float angle)
Description copied from class: PGraphics
Rotate around the Z axis. The functions rotate() and rotateZ() are identical, it's just that it make sense to have rotate() and then rotateX() and rotateY() when using 3D; nor does it make sense to use a function called rotateZ() if you're only doing things in 2D. so we just decided to have them both be the same.

Overrides:
rotateZ in class PGraphics

rotate

public void rotate(float angle,
                   float v0,
                   float v1,
                   float v2)
Rotate around an arbitrary vector, similar to glRotate(), except that it takes radians (instead of degrees).

Overrides:
rotate in class PGraphics

scale

public void scale(float s)
Same as scale(s, s, s).

Overrides:
scale in class PGraphics

scale

public void scale(float sx,
                  float sy)
Same as scale(sx, sy, 1).

Overrides:
scale in class PGraphics

scale

public void scale(float x,
                  float y,
                  float z)
Scale in three dimensions.

Overrides:
scale in class PGraphics

resetMatrix

public void resetMatrix()
Description copied from class: PGraphics
Set the current transformation matrix to identity.

Overrides:
resetMatrix in class PGraphics

applyMatrix

public void applyMatrix(PMatrix2D source)
Overrides:
applyMatrix in class PGraphics

applyMatrix

public void applyMatrix(float n00,
                        float n01,
                        float n02,
                        float n10,
                        float n11,
                        float n12)
Description copied from class: PGraphics
Apply a 3x2 affine transformation matrix.

Overrides:
applyMatrix in class PGraphics

applyMatrix

public void applyMatrix(PMatrix3D source)
Overrides:
applyMatrix in class PGraphics

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)
Apply a 4x4 transformation matrix. Same as glMultMatrix(). This call will be slow because it will try to calculate the inverse of the transform. So avoid it whenever possible.

Overrides:
applyMatrix in class PGraphics

getMatrix

public PMatrix getMatrix()
Overrides:
getMatrix in class PGraphics

getMatrix

public PMatrix3D getMatrix(PMatrix3D target)
Description copied from class: PGraphics
Copy the current transformation matrix into the specified target. Pass in null to create a new matrix.

Overrides:
getMatrix in class PGraphics

setMatrix

public void setMatrix(PMatrix2D source)
Description copied from class: PGraphics
Set the current transformation to the contents of the specified source.

Overrides:
setMatrix in class PGraphics

setMatrix

public void setMatrix(PMatrix3D source)
Set the current transformation to the contents of the specified source.

Overrides:
setMatrix in class PGraphics

printMatrix

public void printMatrix()
Print the current model (or "transformation") matrix.

Overrides:
printMatrix in class PGraphics

beginCamera

public void beginCamera()
Set matrix mode to the camera matrix (instead of the current transformation matrix). This means applyMatrix, resetMatrix, etc. will affect the camera.

Note that the camera matrix is *not* the perspective matrix, it is in front of the modelview matrix (hence the name "model" and "view" for that matrix).

beginCamera() specifies that all coordinate transforms until endCamera() should be pre-applied in inverse to the camera transform matrix. Note that this is only challenging when a user specifies an arbitrary matrix with applyMatrix(). Then that matrix will need to be inverted, which may not be possible. But take heart, if a user is applying a non-invertible matrix to the camera transform, then he is clearly up to no good, and we can wash our hands of those bad intentions.

begin/endCamera clauses do not automatically reset the camera transform matrix. That's because we set up a nice default camera transform int setup(), and we expect it to hold through draw(). So we don't reset the camera transform matrix at the top of draw(). That means that an innocuous-looking clause like 

 beginCamera();
 translate(0, 0, 10);
 endCamera();
at the top of draw(), will result in a runaway camera that shoots infinitely out of the screen over time. In order to prevent this, it is necessary to call some function that does a hard reset of the camera transform matrix inside of begin/endCamera. Two options are 
 camera(); // sets up the nice default camera transform
 resetMatrix(); // sets up the identity camera transform
So to rotate a camera a constant amount, you might try 
 beginCamera();
 camera();
 rotateY(PI/8);
 endCamera();

Overrides:
beginCamera in class PGraphics

endCamera

public void endCamera()
Record the current settings into the camera matrix, and set the matrix mode back to the current transformation matrix.

Note that this will destroy any settings to scale(), translate(), or whatever, because the final camera matrix will be copied (not multiplied) into the modelview.

Overrides:
endCamera in class PGraphics

camera

public void camera()
Set camera to the default settings.

Processing camera behavior:

Camera behavior can be split into two separate components, camera transformation, and projection. The transformation corresponds to the physical location, orientation, and scale of the camera. In a physical camera metaphor, this is what can manipulated by handling the camera body (with the exception of scale, which doesn't really have a physcial analog). The projection corresponds to what can be changed by manipulating the lens.

We maintain separate matrices to represent the camera transform and projection. An important distinction between the two is that the camera transform should be invertible, where the projection matrix should not, since it serves to map three dimensions to two. It is possible to bake the two matrices into a single one just by multiplying them together, but it isn't a good idea, since lighting, z-ordering, and z-buffering all demand a true camera z coordinate after modelview and camera transforms have been applied but before projection. If the camera transform and projection are combined there is no way to recover a good camera-space z-coordinate from a model coordinate.

Fortunately, there are no functions that manipulate both camera transformation and projection.

camera() sets the camera position, orientation, and center of the scene. It replaces the camera transform with a new one. This is different from gluLookAt(), but I think the only reason that GLU's lookat doesn't fully replace the camera matrix with the new one, but instead multiplies it, is that GL doesn't enforce the separation of camera transform and projection, so it wouldn't be safe (you'd probably stomp your projection).

The transformation functions are the same ones used to manipulate the modelview matrix (scale, translate, rotate, etc.). But they are bracketed with beginCamera(), endCamera() to indicate that they should apply (in inverse), to the camera transformation matrix.

This differs considerably from camera transformation in OpenGL. OpenGL only lets you say, apply everything from here out to the projection or modelview matrix. This makes it very hard to treat camera manipulation as if it were a physical camera. Imagine that you want to move your camera 100 units forward. In OpenGL, you need to apply the inverse of that transformation or else you'll move your scene 100 units forward--whether or not you've specified modelview or projection matrix. Remember they're just multiplied by model coods one after another. So in order to treat a camera like a physical camera, it is necessary to pre-apply inverse transforms to a matrix that will be applied to model coordinates. OpenGL provides nothing of this sort, but Processing does! This is the camera transform matrix.

Overrides:
camera in class PGraphics

camera

public void camera(float eyeX,
                   float eyeY,
                   float eyeZ,
                   float centerX,
                   float centerY,
                   float centerZ,
                   float upX,
                   float upY,
                   float upZ)
More flexible method for dealing with camera().

The actual call is like gluLookat. Here's the real skinny on what does what: 

 camera(); or
 camera(ex, ey, ez, cx, cy, cz, ux, uy, uz);
do not need to be called from with beginCamera();/endCamera(); That's because they always apply to the camera transformation, and they always totally replace it. That means that any coordinate transforms done before camera(); in draw() will be wiped out. It also means that camera() always operates in untransformed world coordinates. Therefore it is always redundant to call resetMatrix(); before camera(); This isn't technically true of gluLookat, but it's pretty much how it's used.

Now, beginCamera(); and endCamera(); are useful if you want to move the camera around using transforms like translate(), etc. They will wipe out any coordinate system transforms that occur before them in draw(), but they will not automatically wipe out the camera transform. This means that they should be at the top of draw(). It also means that the following: 

 beginCamera();
 rotateY(PI/8);
 endCamera();
will result in a camera that spins without stopping. If you want to just rotate a small constant amount, try this: 
 beginCamera();
 camera(); // sets up the default view
 rotateY(PI/8);
 endCamera();
That will rotate a little off of the default view. Note that this is entirely equivalent to 
 camera(); // sets up the default view
 beginCamera();
 rotateY(PI/8);
 endCamera();
because camera() doesn't care whether or not it's inside a begin/end clause. Basically it's safe to use camera() or camera(ex, ey, ez, cx, cy, cz, ux, uy, uz) as naked calls because they do all the matrix resetting automatically.

Overrides:
camera in class PGraphics

printCamera

public void printCamera()
Print the current camera matrix.

Overrides:
printCamera in class PGraphics

ortho

public void ortho()
Calls ortho() with the proper parameters for Processing's standard orthographic projection.

Overrides:
ortho in class PGraphics

ortho

public void ortho(float left,
                  float right,
                  float bottom,
                  float top,
                  float near,
                  float far)
Similar to gluOrtho(), but wipes out the current projection matrix.

Implementation partially based on Mesa's matrix.c.

Overrides:
ortho in class PGraphics

perspective

public void perspective()
Calls perspective() with Processing's standard coordinate projection.

Projection functions:

Each of these three functions completely replaces the projection matrix with a new one. They can be called inside setup(), and their effects will be felt inside draw(). At the top of draw(), the projection matrix is not reset. Therefore the last projection function to be called always dominates. On resize, the default projection is always established, which has perspective.

This behavior is pretty much familiar from OpenGL, except where functions replace matrices, rather than multiplying against the previous.

Overrides:
perspective in class PGraphics

perspective

public void perspective(float fov,
                        float aspect,
                        float zNear,
                        float zFar)
Similar to gluPerspective(). Implementation based on Mesa's glu.c

Overrides:
perspective in class PGraphics

frustum

public void frustum(float left,
                    float right,
                    float bottom,
                    float top,
                    float znear,
                    float zfar)
Same as glFrustum(), except that it wipes out (rather than multiplies against) the current perspective matrix.

Implementation based on the explanation in the OpenGL blue book.

Overrides:
frustum in class PGraphics

printProjection

public void printProjection()
Print the current projection matrix.

Overrides:
printProjection in class PGraphics

screenX

public float screenX(float x,
                     float y)
Description copied from class: PGraphics
Given an x and y coordinate, returns the x position of where that point would be placed on screen, once affected by translate(), scale(), or any other transformations.

Overrides:
screenX in class PGraphics

screenY

public float screenY(float x,
                     float y)
Description copied from class: PGraphics
Given an x and y coordinate, returns the y position of where that point would be placed on screen, once affected by translate(), scale(), or any other transformations.

Overrides:
screenY in class PGraphics

screenX

public float screenX(float x,
                     float y,
                     float z)
Description copied from class: PGraphics
Maps a three dimensional point to its placement on-screen.

Given an (x, y, z) coordinate, returns the x position of where that point would be placed on screen, once affected by translate(), scale(), or any other transformations.

Overrides:
screenX in class PGraphics

screenY

public float screenY(float x,
                     float y,
                     float z)
Description copied from class: PGraphics
Maps a three dimensional point to its placement on-screen.

Given an (x, y, z) coordinate, returns the y position of where that point would be placed on screen, once affected by translate(), scale(), or any other transformations.

Overrides:
screenY in class PGraphics

screenZ

public float screenZ(float x,
                     float y,
                     float z)
Description copied from class: PGraphics
Maps a three dimensional point to its placement on-screen.

Given an (x, y, z) coordinate, returns its z value. This value can be used to determine if an (x, y, z) coordinate is in front or in back of another (x, y, z) coordinate. The units are based on how the zbuffer is set up, and don't relate to anything "real". They're only useful for in comparison to another value obtained from screenZ(), or directly out of the zbuffer[].

Overrides:
screenZ in class PGraphics

modelX

public float modelX(float x,
                    float y,
                    float z)
Description copied from class: PGraphics
Returns the model space x value for an x, y, z coordinate.

This will give you a coordinate after it has been transformed by translate(), rotate(), and camera(), but not yet transformed by the projection matrix. For instance, his can be useful for figuring out how points in 3D space relate to the edge coordinates of a shape.

Overrides:
modelX in class PGraphics

modelY

public float modelY(float x,
                    float y,
                    float z)
Description copied from class: PGraphics
Returns the model space y value for an x, y, z coordinate.

Overrides:
modelY in class PGraphics

modelZ

public float modelZ(float x,
                    float y,
                    float z)
Description copied from class: PGraphics
Returns the model space z value for an x, y, z coordinate.

Overrides:
modelZ in class PGraphics

strokeJoin

public void strokeJoin(int join)
Overrides:
strokeJoin in class PGraphics

strokeCap

public void strokeCap(int cap)
Overrides:
strokeCap in class PGraphics

lights

public void lights()
Sets up an ambient and directional light. 
 The Lighting Skinny:

 The way lighting works is complicated enough that it's worth
 producing a document to describe it. Lighting calculations proceed
 pretty much exactly as described in the OpenGL red book.

 Light-affecting material properties:

   AMBIENT COLOR
   - multiplies by light's ambient component
   - for believability this should match diffuse color

   DIFFUSE COLOR
   - multiplies by light's diffuse component

   SPECULAR COLOR
   - multiplies by light's specular component
   - usually less colored than diffuse/ambient

   SHININESS
   - the concentration of specular effect
   - this should be set pretty high (20-50) to see really
     noticeable specularity

   EMISSIVE COLOR
   - constant additive color effect

 Light types:

   AMBIENT
   - one color
   - no specular color
   - no direction
   - may have falloff (constant, linear, and quadratic)
   - may have position (which matters in non-constant falloff case)
   - multiplies by a material's ambient reflection

   DIRECTIONAL
   - has diffuse color
   - has specular color
   - has direction
   - no position
   - no falloff
   - multiplies by a material's diffuse and specular reflections

   POINT
   - has diffuse color
   - has specular color
   - has position
   - no direction
   - may have falloff (constant, linear, and quadratic)
   - multiplies by a material's diffuse and specular reflections

   SPOT
   - has diffuse color
   - has specular color
   - has position
   - has direction
   - has cone angle (set to half the total cone angle)
   - has concentration value
   - may have falloff (constant, linear, and quadratic)
   - multiplies by a material's diffuse and specular reflections

 Normal modes:

 All of the primitives (rect, box, sphere, etc.) have their normals
 set nicely. During beginShape/endShape normals can be set by the user.

   AUTO-NORMAL
   - if no normal is set during the shape, we are in auto-normal mode
   - auto-normal calculates one normal per triangle (face-normal mode)

   SHAPE-NORMAL
   - if one normal is set during the shape, it will be used for
     all vertices

   VERTEX-NORMAL
   - if multiple normals are set, each normal applies to
     subsequent vertices
   - (except for the first one, which applies to previous
     and subsequent vertices)

 Efficiency consequences:

   There is a major efficiency consequence of position-dependent
   lighting calculations per vertex. (See below for determining
   whether lighting is vertex position-dependent.) If there is no
   position dependency then the only factors that affect the lighting
   contribution per vertex are its colors and its normal.
   There is a major efficiency win if

   1) lighting is not position dependent
   2) we are in AUTO-NORMAL or SHAPE-NORMAL mode

   because then we can calculate one lighting contribution per shape
   (SHAPE-NORMAL) or per triangle (AUTO-NORMAL) and simply multiply it
   into the vertex colors. The converse is our worst-case performance when

   1) lighting is position dependent
   2) we are in AUTO-NORMAL mode

   because then we must calculate lighting per-face * per-vertex.
   Each vertex has a different lighting contribution per face in
   which it appears. Yuck.

 Determining vertex position dependency:

   If any of the following factors are TRUE then lighting is
   vertex position dependent:

   1) Any lights uses non-constant falloff
   2) There are any point or spot lights
   3) There is a light with specular color AND there is a
      material with specular color

 So worth noting is that default lighting (a no-falloff ambient
 and a directional without specularity) is not position-dependent.
 We should capitalize.

 Simon Greenwold, April 2005

Overrides:
lights in class PGraphics

noLights

public void noLights()
Turn off all lights.

Overrides:
noLights in class PGraphics

ambientLight

public void ambientLight(float r,
                         float g,
                         float b)
Add an ambient light based on the current color mode.

Overrides:
ambientLight in class PGraphics

ambientLight

public void ambientLight(float r,
                         float g,
                         float b,
                         float x,
                         float y,
                         float z)
Add an ambient light based on the current color mode. This version includes an (x, y, z) position for situations where the falloff distance is used.

Overrides:
ambientLight in class PGraphics

directionalLight

public void directionalLight(float r,
                             float g,
                             float b,
                             float nx,
                             float ny,
                             float nz)
Overrides:
directionalLight in class PGraphics

pointLight

public void pointLight(float r,
                       float g,
                       float b,
                       float x,
                       float y,
                       float z)
Overrides:
pointLight in class PGraphics

spotLight

public void spotLight(float r,
                      float g,
                      float b,
                      float x,
                      float y,
                      float z,
                      float nx,
                      float ny,
                      float nz,
                      float angle,
                      float concentration)
Overrides:
spotLight in class PGraphics

lightFalloff

public void lightFalloff(float constant,
                         float linear,
                         float quadratic)
Set the light falloff rates for the last light that was created. Default is lightFalloff(1, 0, 0).

Overrides:
lightFalloff in class PGraphics

lightSpecular

public void lightSpecular(float x,
                          float y,
                          float z)
Set the specular color of the last light created.

Overrides:
lightSpecular in class PGraphics

is2D

public boolean is2D()
Description copied from class: PGraphics
Return true if this renderer supports 2D drawing. Defaults to true.

Overrides:
is2D in class PGraphics

is3D

public boolean is3D()
Description copied from class: PGraphics
Return true if this renderer supports 2D drawing. Defaults to true.

Overrides:
is3D in class PGraphics
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD