eessppeelllloo/processing4
1
0
Fork 0
mirror of https://github.com/processing/processing4.git synced 2026-06-16 04:26:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Flesh out the Javadoc for PMatrix.

Browse Source
This commit is contained in:
George Bateman
2015-11-16 19:57:07 +00:00
parent f2c32f5143
commit b238d50e5b
3 changed files with 217 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/src/processing/core/PMatrix.java
+64 -8
View File
@@ -24,8 +24,21 @@
package processing.core;
/**
* A matrix is used to define graphical transformations. PMatrix is the common
* interface for both the 2D and 3D matrix classes in Processing. A matrix is a
* grid of numbers, which can be multiplied by a vector to give another vector.
* Multiplying a point by a particular matrix might translate it, rotate it,
* or carry out a combination of transformations.
*
* Multiplying matrices by each other combines their effects; use the
* {@code apply} and {@code preApply} methods for this.
*/
public interface PMatrix {
/**
* Make this an identity matrix. Multiplying by it will have no effect.
*/
public void reset();
/**
@@ -40,13 +53,26 @@ public interface PMatrix {
public float[] get(float[] target);
/**
* Make this matrix become a copy of src.
*/
public void set(PMatrix src);
/**
* Set the contents of this matrix to the contents of source. Fills the
* matrix left-to-right, starting in the top row.
*/
public void set(float[] source);
/**
* Set the matrix content to this 2D matrix or its 3D equivalent.
*/
public void set(float m00, float m01, float m02,
float m10, float m11, float m12);
/**
* Set the matrix content to the 3D matrix supplied, if this matrix is 3D.
*/
public void set(float m00, float m01, float m02, float m03,
float m10, float m11, float m12, float m13,
float m20, float m21, float m22, float m23,
@@ -77,18 +103,30 @@ public interface PMatrix {
public void shearY(float angle);
/**
/**
* Multiply this matrix by another.
*/
public void apply(PMatrix source);
/**
* Multiply this matrix by another.
*/
public void apply(PMatrix2D source);
/**
* Multiply this matrix by another.
*/
public void apply(PMatrix3D source);
/**
* Multiply this matrix by another.
*/
public void apply(float n00, float n01, float n02,
float n10, float n11, float n12);
/**
* Multiply this matrix by another.
*/
public void apply(float n00, float n01, float n02, float n03,
float n10, float n11, float n12, float n13,
float n20, float n21, float n22, float n23,
@@ -99,27 +137,44 @@ public interface PMatrix {
*/
public void preApply(PMatrix left);
/**
* Apply another matrix to the left of this one.
*/
public void preApply(PMatrix2D left);
/**
* Apply another matrix to the left of this one. 3D only.
*/
public void preApply(PMatrix3D left);
/**
* Apply another matrix to the left of this one.
*/
public void preApply(float n00, float n01, float n02,
float n10, float n11, float n12);
/**
* Apply another matrix to the left of this one. 3D only.
*/
public void preApply(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);
/**
* Multiply a PVector by this matrix.
/**
* Multiply source by this matrix, and return the result.
* The result will be stored in target if target is non-null, and target
* will then be the matrix returned. This improves performance if you reuse
* target, so it's recommended if you call this many times in draw().
*/
public PVector mult(PVector source, PVector target);
/**
* Multiply a multi-element vector against this matrix.
/**
* Multiply a multi-element vector against this matrix.
* Supplying and recycling a target array improves performance, so it's
* recommended if you call this many times in draw().
*/
public float[] mult(float[] source, float[] target);
@@ -133,13 +188,14 @@ public interface PMatrix {
/**
* Transpose this matrix.
* Transpose this matrix; rows become columns and columns rows.
*/
public void transpose();
/**
* Invert this matrix.
* Invert this matrix. Will not necessarily succeed, because some matrices
* map more than one point to the same image point, and so are irreversible.
* @return true if successful
*/
public boolean invert();
@@ -149,4 +205,4 @@ public interface PMatrix {
* @return the determinant of the matrix
*/
public float determinant();
}
}
core/src/processing/core/PMatrix2D.java
+76 -5
View File
@@ -26,6 +26,15 @@ package processing.core;
/**
* 3x2 affine matrix implementation.
* Matrices are used to describe a transformation; see {@link PMatrix} for a
* general description. This matrix looks like the following when multiplying
* a vector (x, y) in {@code mult()}.
* <pre>
* [m00 m01 m02][x] [m00*x + m01*y + m02*1] [x']
* [m10 m11 m12][y] = [m10*x + m11*y + m12*1] = [y']
* [ 0 0 1 ][1] [ 0*x + 0*y + 1*1 ] [ 1]</pre>
* (x', y') is returned. The values in the matrix determine the transformation.
* They are modified by the various transformation functions.
*/
public class PMatrix2D implements PMatrix {
@@ -33,6 +42,9 @@ public class PMatrix2D implements PMatrix {
public float m10, m11, m12;
/**
* Create a new matrix, set to the identity matrix.
*/
public PMatrix2D() {
reset();
}
@@ -69,6 +81,7 @@ public class PMatrix2D implements PMatrix {
/**
* Copies the matrix contents into a 6 entry float array.
* If target is null (or not the correct size), a new array will be created.
* Returned in the order {@code {m00, m01, m02, m10, m11, m12}}.
*/
public float[] get(float[] target) {
if ((target == null) || (target.length != 6)) {
@@ -86,6 +99,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* If matrix is a PMatrix2D, sets this matrix to be a copy of it.
* @throws IllegalArgumentException If <tt>matrix</tt> is not 2D.
*/
public void set(PMatrix matrix) {
if (matrix instanceof PMatrix2D) {
PMatrix2D src = (PMatrix2D) matrix;
@@ -97,6 +114,9 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D. Does nothing.
*/
public void set(PMatrix3D src) {
}
@@ -112,6 +132,9 @@ public class PMatrix2D implements PMatrix {
}
/**
* Sets the matrix content.
*/
public void set(float m00, float m01, float m02,
float m10, float m11, float m12) {
this.m00 = m00; this.m01 = m01; this.m02 = m02;
@@ -119,6 +142,9 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D. Does nothing.
*/
public void set(float m00, float m01, float m02, float m03,
float m10, float m11, float m12, float m13,
float m20, float m21, float m22, float m23,
@@ -133,6 +159,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void translate(float x, float y, float z) {
throw new IllegalArgumentException("Cannot use translate(x, y, z) on a PMatrix2D.");
}
@@ -154,11 +184,19 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void rotateX(float angle) {
throw new IllegalArgumentException("Cannot use rotateX() on a PMatrix2D.");
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void rotateY(float angle) {
throw new IllegalArgumentException("Cannot use rotateY() on a PMatrix2D.");
}
@@ -169,6 +207,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void rotate(float angle, float v0, float v1, float v2) {
throw new IllegalArgumentException("Cannot use this version of rotate() on a PMatrix2D.");
}
@@ -185,6 +227,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void scale(float x, float y, float z) {
throw new IllegalArgumentException("Cannot use this version of scale() on a PMatrix2D.");
}
@@ -215,6 +261,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void apply(PMatrix3D source) {
throw new IllegalArgumentException("Cannot use apply(PMatrix3D) on a PMatrix2D.");
}
@@ -236,6 +286,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void apply(float n00, float n01, float n02, float n03,
float n10, float n11, float n12, float n13,
float n20, float n21, float n22, float n23,
@@ -262,6 +316,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void preApply(PMatrix3D left) {
throw new IllegalArgumentException("Cannot use preApply(PMatrix3D) on a PMatrix2D.");
}
@@ -289,6 +347,10 @@ public class PMatrix2D implements PMatrix {
}
/**
* Unavailable in 2D.
* @throws IllegalArgumentException
*/
public void preApply(float n00, float n01, float n02, float n03,
float n10, float n11, float n12, float n13,
float n20, float n21, float n22, float n23,
@@ -301,7 +363,8 @@ public class PMatrix2D implements PMatrix {
/**
* Multiply the x and y coordinates of a PVector against this matrix.
* {@inheritDoc}
* Ignores any z component.
*/
public PVector mult(PVector source, PVector target) {
if (target == null) {
@@ -339,26 +402,34 @@ public class PMatrix2D implements PMatrix {
}
/**
* Returns the x-coordinate of the result of multiplying the point (x, y)
* by this matrix.
*/
public float multX(float x, float y) {
return m00*x + m01*y + m02;
}
/**
* Returns the y-coordinate of the result of multiplying the point (x, y)
* by this matrix.
*/
public float multY(float x, float y) {
return m10*x + m11*y + m12;
}
/**
* Transpose this matrix.
* Unavailable in 2D. Does nothing.
*/
public void transpose() {
}
/**
* Invert this matrix. Implementation stolen from OpenJDK.
* @return true if successful
/*
* Implementation stolen from OpenJDK.
*/
public boolean invert() {
float determinant = determinant();
core/src/processing/core/PMatrix3D.java
+77 -2
View File
@@ -25,6 +25,20 @@ package processing.core;
/**
* 4x4 matrix implementation.
* Matrices are used to describe a transformation; see {@link PMatrix} for a
* general description. This matrix looks like the following when multiplying
* a vector (x, y, z, w) in {@code mult()}.
* <pre>
* [m00 m01 m02 m03][x] [m00*x + m01*y + m02*z + m03*w] [x']
* [m10 m11 m12 m13][y] = [m10*x + m11*y + m12*z + m13*w] = [y']
* [m20 m21 m22 m23][z] [m20*x + m21*y + m22*z + m23*w] [z']
* [m30 m31 m32 m33][w] [m30*x + m31*y + m32*z + m33*w] [w']</pre>
* (x', y', z', w') is returned. The values in the matrix determine the
* transformation. They are modified by the various transformation functions.
*
* To transform 3D coordinates, w is set to 1, amd w' is made to be 1 by
* setting the bottom row of the matrix to <code>[0 0 0 1]</code>. The
* resulting point is then (x', y', z').
*/
public final class PMatrix3D implements PMatrix /*, PConstants*/ {
@@ -358,6 +372,9 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
}
/**
* Apply the 3D equivalent of the 2D matrix supplied to the left of this one.
*/
public void preApply(PMatrix2D left) {
preApply(left.m00, left.m01, 0, left.m02,
left.m10, left.m11, 0, left.m12,
@@ -378,6 +395,9 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
}
/**
* Apply another matrix to the left of this one.
*/
public void preApply(PMatrix3D left) {
preApply(left.m00, left.m01, left.m02, left.m03,
left.m10, left.m11, left.m12, left.m13,
@@ -386,6 +406,9 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
}
/**
* Apply the 3D equivalent of the 2D matrix supplied to the left of this one.
*/
public void preApply(float n00, float n01, float n02,
float n10, float n11, float n12) {
preApply(n00, n01, 0, n02,
@@ -395,6 +418,9 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
}
/**
* Apply another matrix to the left of this one.
*/
public void preApply(float n00, float n01, float n02, float n03,
float n10, float n11, float n12, float n13,
float n20, float n21, float n22, float n23,
@@ -430,6 +456,12 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
//////////////////////////////////////////////////////////////
/**
* Multiply source by this matrix, and return the result.
* The result will be stored in target if target is non-null, and target
* will then be the matrix returned. This improves performance if you reuse
* target, so it's recommended if you call this many times in draw().
*/
public PVector mult(PVector source, PVector target) {
if (target == null) {
target = new PVector();
@@ -465,6 +497,8 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
/**
* Multiply a three or four element vector against this matrix. If out is
* null or not length 3 or 4, a new float array (length 3) will be returned.
* Supplying and recycling a target array improves performance, so it's
* recommended if you call this many times in draw.
*/
public float[] mult(float[] source, float[] target) {
if (target == null || target.length < 3) {
@@ -492,58 +526,98 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
}
/**
* Returns the x-coordinate of the result of multiplying the point (x, y)
* by this matrix.
*/
public float multX(float x, float y) {
return m00*x + m01*y + m03;
}
/**
* Returns the y-coordinate of the result of multiplying the point (x, y)
* by this matrix.
*/
public float multY(float x, float y) {
return m10*x + m11*y + m13;
}
/**
* Returns the x-coordinate of the result of multiplying the point (x, y, z)
* by this matrix.
*/
public float multX(float x, float y, float z) {
return m00*x + m01*y + m02*z + m03;
}
/**
* Returns the y-coordinate of the result of multiplying the point (x, y, z)
* by this matrix.
*/
public float multY(float x, float y, float z) {
return m10*x + m11*y + m12*z + m13;
}
/**
* Returns the z-coordinate of the result of multiplying the point (x, y, z)
* by this matrix.
*/
public float multZ(float x, float y, float z) {
return m20*x + m21*y + m22*z + m23;
}
/**
* Returns the fourth element of the result of multiplying the vector
* (x, y, z) by this matrix. (Acts as if w = 1 was supplied.)
*/
public float multW(float x, float y, float z) {
return m30*x + m31*y + m32*z + m33;
}
/**
* Returns the x-coordinate of the result of multiplying the vector
* (x, y, z, w) by this matrix.
*/
public float multX(float x, float y, float z, float w) {
return m00*x + m01*y + m02*z + m03*w;
}
/**
* Returns the y-coordinate of the result of multiplying the vector
* (x, y, z, w) by this matrix.
*/
public float multY(float x, float y, float z, float w) {
return m10*x + m11*y + m12*z + m13*w;
}
/**
* Returns the z-coordinate of the result of multiplying the vector
* (x, y, z, w) by this matrix.
*/
public float multZ(float x, float y, float z, float w) {
return m20*x + m21*y + m22*z + m23*w;
}
/**
* Returns the w-coordinate of the result of multiplying the vector
* (x, y, z, w) by this matrix.
*/
public float multW(float x, float y, float z, float w) {
return m30*x + m31*y + m32*z + m33*w;
}
/**
* Transpose this matrix.
* Transpose this matrix; rows become columns and columns rows.
*/
public void transpose() {
float temp;
@@ -557,7 +631,8 @@ public final class PMatrix3D implements PMatrix /*, PConstants*/ {
/**
* Invert this matrix.
* Invert this matrix. Will not necessarily succeed, because some matrices
* map more than one point to the same image point, and so are irreversible.
* @return true if successful
*/
public boolean invert() {