processing.core
Class PGraphics3D

java.lang.Object
  processing.core.PImage
      processing.core.PGraphics
          processing.core.PGraphics3D

All Implemented Interfaces:

java.lang.Cloneable, PConstants

public class PGraphics3D
extends PGraphics

Subclass of PGraphics that handles 3D rendering for Java 1.1. 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.

line

public PLine line

triangle

public PTriangle triangle

shape_index

public int shape_index

PGraphics3D

public PGraphics3D(int iwidth,
                   int iheight,
                   PApplet parent)

Constructor for the PGraphics3 object. Use this to ensure that the defaults get set properly. In a subclass, use this(w, h) as the first line of a subclass' constructor to properly set the internal fields and defaults.

Parameters:

iwidth - viewport width

iheight - viewport height

resize

public void resize(int iwidth,
                   int iheight)

Called in repsonse 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:

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

Specified by:

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.

Specified by:

endDraw in class PGraphics

defaultSettings

public void defaultSettings()

Description copied from class: PGraphics

Set engine's default values. This has to be called by PApplet, somewhere inside setup() or draw() because it talks to the graphics buffer, meaning that for subclasses like OpenGL, there needs to be a valid graphics context to mess with otherwise you'll get some good crashing action.

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.

Specified by:

beginShape in class PGraphics

normal

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

Sets the current normal vector.

This is for drawing three dimensional shapes and surfaces, allowing you to specify a vector perpendicular to the surface of the shape, which determines how lighting affects it.

For the most part, PGraphics3D will attempt to automatically assign normals to shapes, but since that's imperfect, this is a better option when you want more control.

For people familiar with OpenGL, this function is basically identical to glNormal3f().

Only applies inside a beginShape/endShape block.

Overrides:

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

Specified by:

vertex in class PGraphics

vertex

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

Specified by:

vertex in class PGraphics

vertex

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

Specified by:

vertex in class PGraphics

vertex

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

Specified by:

vertex in class PGraphics

bezierVertex

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

See notes with the bezier() function.

Overrides:

bezierVertex in class PGraphics

bezierVertex

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

See notes with the bezier() function.

Overrides:

bezierVertex in class PGraphics

endShape

public void endShape(int mode)

Specified by:

endShape in class PGraphics

point

public void point(float x,
                  float y)

Description copied from class: PGraphics

End a path. Use this with beginPath() to close out a compound path.

This will probably be available only with the OpenGL renderer, because it has a built-in tesselator from GLU.

Overrides:

point in class PGraphics

point

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

Overrides:

point in class PGraphics

triangle

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

Compared to the implementation in PGraphics, this adds normal().

Overrides:

triangle in class PGraphics

quad

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

Compared to the implementation in PGraphics, this adds normal().

Overrides:

quad in class PGraphics

box

public void box(float size)

Overrides:

box in class PGraphics

box

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

Overrides:

box in class PGraphics

sphereDetail

public void sphereDetail(int res)

Overrides:

sphereDetail in class PGraphics

sphereDetail

public void sphereDetail(int ures,
                         int vres)

Set the detail level for approximating a sphere. The ures and vres params control the horizontal and vertical resolution. Code for sphereDetail() submitted by toxi [031031]. Code for enhanced u/v version from davbol [080801].

Overrides:

sphereDetail in class PGraphics

sphere

public void sphere(float r)

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

translate

public void translate(float tx,
                      float ty)

Overrides:

translate in class PGraphics

translate

public void translate(float tx,
                      float ty,
                      float tz)

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)

Overrides:

rotateX in class PGraphics

rotateY

public void rotateY(float angle)

Overrides:

rotateY in class PGraphics

rotateZ

public void rotateZ(float angle)

Rotate in the XY plane by an angle. Note that this doesn't internally set the number of dimensions to three, since rotateZ() is the same as a 2D rotate in the XY plane.

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)

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. Equivalent to 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

pushMatrix

public void pushMatrix()

Overrides:

pushMatrix in class PGraphics

popMatrix

public void popMatrix()

Overrides:

popMatrix in class PGraphics

resetMatrix

public void resetMatrix()

Load identity as the transform/model matrix. Same as glLoadIdentity().

Overrides:

resetMatrix 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(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

loadMatrix

public void loadMatrix()

Load the modelview into m00, m01, et al so that it can be used.

Overrides:

loadMatrix 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:

• frustrum()
• ortho()
• perspective()

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

ambient

public void ambient(int rgb)

Overrides:

ambient in class PGraphics

ambient

public void ambient(float gray)

Overrides:

ambient in class PGraphics

ambient

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

Overrides:

ambient in class PGraphics

specular

public void specular(int rgb)

Overrides:

specular in class PGraphics

specular

public void specular(float gray)

Overrides:

specular in class PGraphics

specular

public void specular(float gray,
                     float alpha)

Overrides:

specular in class PGraphics

specular

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

Overrides:

specular in class PGraphics

specular

public void specular(float x,
                     float y,
                     float z,
                     float a)

Overrides:

specular in class PGraphics

shininess

public void shininess(float shine)

Overrides:

shininess in class PGraphics

emissive<