processing.core

## Class PVector

- Object
- - PVector

- All Implemented Interfaces:
    Serializable

      public class PVector
      extends Object
      implements Serializable

  ( begin auto-generated from PVector.xml ) A class to describe a two or three dimensional vector. This datatype stores two or three variables that are commonly used as a position, velocity, and/or acceleration. Technically, position is a point and velocity and acceleration are vectors, but this is often simplified to consider all three as vectors. For example, if you consider a rectangle moving across the screen, at any given instant it has a position (the object's location, expressed as a point.), a velocity (the rate at which the object's position changes per time unit, expressed as a vector), and acceleration (the rate at which the object's velocity changes per time unit, expressed as a vector). Since vectors represent groupings of values, we cannot simply use traditional addition/multiplication/etc. Instead, we'll need to do some "vector" math, which is made easy by the methods inside the PVector class.
  The methods for this class are extensive. For a complete list, visit the developer's reference. ( end auto-generated ) A class to describe a two or three dimensional vector.

  The result of all functions are applied to the vector itself, with the exception of cross(), which returns a new PVector (or writes to a specified 'target' PVector). That is, add() will add the contents of one vector to this one. Using add() with additional parameters allows you to put the result into a new PVector. Functions that act on multiple vectors also include static versions. Because creating new objects can be computationally expensive, most functions include an optional 'target' PVector, so that a new PVector object is not created with each operation.

  Initially based on the Vector3D class by Dan Shiffman.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `float` | `x` ( begin auto-generated from PVector_x.xml ) The x component of the vector.
    `float` | `y` ( begin auto-generated from PVector_y.xml ) The y component of the vector.
    `float` | `z` ( begin auto-generated from PVector_z.xml ) The z component of the vector.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PVector()` Constructor for an empty vector: x, y, and z are set to 0.
    `PVector(float x, float y)` Constructor for a 2D vector: z coordinate is set to 0.
    `PVector(float x, float y, float z)` Constructor for a 3D vector.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(float x, float y, float z)`
    `void` | `add(PVector v)` ( begin auto-generated from PVector_add.xml ) Adds x, y, and z components to a vector, adds one vector to another, or adds two independent vectors together.
    `static PVector` | `add(PVector v1, PVector v2)` Add two vectors
    `static PVector` | `add(PVector v1, PVector v2, PVector target)` Add two vectors into a target vector
    `static float` | `angleBetween(PVector v1, PVector v2)` ( begin auto-generated from PVector_angleBetween.xml ) Calculates and returns the angle (in radians) between two vectors.
    `float[]` | `array()` ( begin auto-generated from PVector_array.xml ) Return a representation of this vector as a float array.
    `PVector` | `cross(PVector v)` ( begin auto-generated from PVector_cross.xml ) Calculates and returns a vector composed of the cross product between two vectors.
    `PVector` | `cross(PVector v, PVector target)`
    `static PVector` | `cross(PVector v1, PVector v2, PVector target)`
    `float` | `dist(PVector v)` ( begin auto-generated from PVector_dist.xml ) Calculates the Euclidean distance between two points (considering a point as a vector object).
    `static float` | `dist(PVector v1, PVector v2)`
    `void` | `div(float n)` ( begin auto-generated from PVector_div.xml ) Divides a vector by a scalar or divides one vector by another.
    `static PVector` | `div(PVector v, float n)` Divide a vector by a scalar and return the result in a new vector.
    `static PVector` | `div(PVector v, float n, PVector target)` Divide a vector by a scalar and store the result in another vector.
    `float` | `dot(float x, float y, float z)`
    `float` | `dot(PVector v)` ( begin auto-generated from PVector_dot.xml ) Calculates the dot product of two vectors.
    `static float` | `dot(PVector v1, PVector v2)`
    `boolean` | `equals(Object obj)`
    `static PVector` | `fromAngle(float angle)` ( begin auto-generated from PVector_sub.xml ) Make a new 2D unit vector from an angle.
    `static PVector` | `fromAngle(float angle, PVector target)` Make a new 2D unit vector from an angle
    `PVector` | `get()` ( begin auto-generated from PVector_get.xml ) Gets a copy of the vector, returns a PVector object.
    `float[]` | `get(float[] target)`
    `int` | `hashCode()`
    `float` | `heading()` ( begin auto-generated from PVector_setMag.xml ) Calculate the angle of rotation for this vector (only 2D vectors) ( end auto-generated )
    `float` | `heading2D()` Deprecated.
    `void` | `lerp(float x, float y, float z, float amt)` Linear interpolate the vector to x,y,z values
    `void` | `lerp(PVector v, float amt)` ( begin auto-generated from PVector_rotate.xml ) Linear interpolate the vector to another vector ( end auto-generated )
    `static PVector` | `lerp(PVector v1, PVector v2, float amt)` Linear interpolate between two vectors (returns a new PVector object)
    `void` | `limit(float max)` ( begin auto-generated from PVector_limit.xml ) Limit the magnitude of this vector to the value used for the max parameter.
    `float` | `mag()` ( begin auto-generated from PVector_mag.xml ) Calculates the magnitude (length) of the vector and returns the result as a float (this is simply the equation sqrt(x*x + y*y + z*z).) ( end auto-generated )
    `float` | `magSq()` ( begin auto-generated from PVector_mag.xml ) Calculates the squared magnitude of the vector and returns the result as a float (this is simply the equation (x*x + y*y + z*z).) Faster if the real length is not required in the case of comparing vectors, etc.
    `void` | `mult(float n)` ( begin auto-generated from PVector_mult.xml ) Multiplies a vector by a scalar or multiplies one vector by another.
    `static PVector` | `mult(PVector v, float n)`
    `static PVector` | `mult(PVector v, float n, PVector target)` Multiply a vector by a scalar, and write the result into a target PVector.
    `void` | `normalize()` ( begin auto-generated from PVector_normalize.xml ) Normalize the vector to length 1 (make it a unit vector).
    `PVector` | `normalize(PVector target)`
    `static PVector` | `random2D()` ( begin auto-generated from PVector_random2D.xml ) Make a new 2D unit vector with a random direction.
    `static PVector` | `random2D(PApplet parent)` Make a new 2D unit vector with a random direction using Processing's current random number generator
    `static PVector` | `random2D(PVector target)` Set a 2D vector to a random unit vector with a random direction
    `static PVector` | `random2D(PVector target, PApplet parent)` Make a new 2D unit vector with a random direction
    `static PVector` | `random3D()` ( begin auto-generated from PVector_random3D.xml ) Make a new 3D unit vector with a random direction.
    `static PVector` | `random3D(PApplet parent)` Make a new 3D unit vector with a random direction using Processing's current random number generator
    `static PVector` | `random3D(PVector target)` Set a 3D vector to a random unit vector with a random direction
    `static PVector` | `random3D(PVector target, PApplet parent)` Make a new 3D unit vector with a random direction
    `void` | `rotate(float theta)` ( begin auto-generated from PVector_rotate.xml ) Rotate the vector by an angle (only 2D vectors), magnitude remains the same ( end auto-generated )
    `void` | `set(float[] source)` Set the x, y (and maybe z) coordinates using a float[] array as the source.
    `void` | `set(float x, float y)`
    `void` | `set(float x, float y, float z)` ( begin auto-generated from PVector_set.xml ) Sets the x, y, and z component of the vector using two or three separate variables, the data from a PVector, or the values from a float array.
    `void` | `set(PVector v)`
    `void` | `setMag(float len)` ( begin auto-generated from PVector_setMag.xml ) Set the magnitude of this vector to the value used for the len parameter.
    `PVector` | `setMag(PVector target, float len)` Sets the magnitude of this vector, storing the result in another vector.
    `void` | `sub(float x, float y, float z)`
    `void` | `sub(PVector v)` ( begin auto-generated from PVector_sub.xml ) Subtracts x, y, and z components from a vector, subtracts one vector from another, or subtracts two independent vectors.
    `static PVector` | `sub(PVector v1, PVector v2)` Subtract one vector from another
    `static PVector` | `sub(PVector v1, PVector v2, PVector target)` Subtract one vector from another and store in another vector
    `String` | `toString()`

    - ### Methods inherited from class Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### x

          public float x

      ( begin auto-generated from PVector_x.xml ) The x component of the vector. This field (variable) can be used to both get and set the value (see above example.) ( end auto-generated )

    - #### y

          public float y

      ( begin auto-generated from PVector_y.xml ) The y component of the vector. This field (variable) can be used to both get and set the value (see above example.) ( end auto-generated )

    - #### z

          public float z

      ( begin auto-generated from PVector_z.xml ) The z component of the vector. This field (variable) can be used to both get and set the value (see above example.) ( end auto-generated )

  - ### Constructor Detail

    - #### PVector

          public PVector()

      Constructor for an empty vector: x, y, and z are set to 0.

    - #### PVector

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

      Constructor for a 3D vector.
      Parameters:
        `x` - the x coordinate.
        `y` - the y coordinate.
        `z` - the z coordinate.

    - #### PVector

          public PVector(float x,
                 float y)

      Constructor for a 2D vector: z coordinate is set to 0.

  - ### Method Detail

    - #### set

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

      ( begin auto-generated from PVector_set.xml ) Sets the x, y, and z component of the vector using two or three separate variables, the data from a PVector, or the values from a float array. ( end auto-generated )
      Parameters:
        `x` - the x component of the vector
        `y` - the y component of the vector
        `z` - the z component of the vector

    - #### set

          public void set(float x,
                 float y)

      Parameters:
        `x` - the x component of the vector
        `y` - the y component of the vector

    - #### set

          public void set(PVector v)

      Parameters:
        `v` - any variable of type PVector

    - #### set

          public void set(float[] source)

      Set the x, y (and maybe z) coordinates using a float[] array as the source.
      Parameters:
        `source` - array to copy from

    - #### random2D

          public static PVector random2D()

      ( begin auto-generated from PVector_random2D.xml ) Make a new 2D unit vector with a random direction. If you pass in "this" as an argument, it will use the PApplet's random number generator. You can also pass in a target PVector to fill.
      Returns:
        the random PVector
      See Also:
        `random3D()`

    - #### random2D

          public static PVector random2D(PApplet parent)

      Make a new 2D unit vector with a random direction using Processing's current random number generator
      Parameters:
        `parent` - current PApplet instance
      Returns:
        the random PVector

    - #### random2D

          public static PVector random2D(PVector target)

      Set a 2D vector to a random unit vector with a random direction
      Parameters:
        `target` - the target vector (if null, a new vector will be created)
      Returns:
        the random PVector

    - #### random2D

          public static PVector random2D(PVector target,
                         PApplet parent)

      Make a new 2D unit vector with a random direction
      Returns:
        the random PVector

    - #### random3D

          public static PVector random3D()

      ( begin auto-generated from PVector_random3D.xml ) Make a new 3D unit vector with a random direction. If you pass in "this" as an argument, it will use the PApplet's random number generator. You can also pass in a target PVector to fill.
      Returns:
        the random PVector
      See Also:
        `random2D()`

    - #### random3D

          public static PVector random3D(PApplet parent)

      Make a new 3D unit vector with a random direction using Processing's current random number generator
      Parameters:
        `parent` - current PApplet instance
      Returns:
        the random PVector

    - #### random3D

          public static PVector random3D(PVector target)

      Set a 3D vector to a random unit vector with a random direction
      Parameters:
        `target` - the target vector (if null, a new vector will be created)
      Returns:
        the random PVector

    - #### random3D

          public static PVector random3D(PVector target,
                         PApplet parent)

      Make a new 3D unit vector with a random direction
      Returns:
        the random PVector

    - #### fromAngle

          public static PVector fromAngle(float angle)

      ( begin auto-generated from PVector_sub.xml ) Make a new 2D unit vector from an angle. ( end auto-generated )
      Parameters:
        `angle` - the angle
      Returns:
        the new unit PVector

    - #### fromAngle

          public static PVector fromAngle(float angle,
                          PVector target)

      Make a new 2D unit vector from an angle
      Parameters:
        `target` - the target vector (if null, a new vector will be created)
      Returns:
        the PVector

    - #### get

          public PVector get()

      ( begin auto-generated from PVector_get.xml ) Gets a copy of the vector, returns a PVector object. ( end auto-generated )

    - #### get

          public float[] get(float[] target)

      Parameters:
        `target` -

    - #### mag

          public float mag()

      ( begin auto-generated from PVector_mag.xml ) Calculates the magnitude (length) of the vector and returns the result as a float (this is simply the equation sqrt(x*x + y*y + z*z).) ( end auto-generated )
      Returns:
        magnitude (length) of the vector
      See Also:
        `magSq()`

    - #### magSq

          public float magSq()

      ( begin auto-generated from PVector_mag.xml ) Calculates the squared magnitude of the vector and returns the result as a float (this is simply the equation (x*x + y*y + z*z).) Faster if the real length is not required in the case of comparing vectors, etc. ( end auto-generated )
      Returns:
        squared magnitude of the vector
      See Also:
        `mag()`

    - #### add

          public void add(PVector v)

      ( begin auto-generated from PVector_add.xml ) Adds x, y, and z components to a vector, adds one vector to another, or adds two independent vectors together. The version of the method that adds two vectors together is a static method and returns a PVector, the others have no return value -- they act directly on the vector. See the examples for more context. ( end auto-generated )
      Parameters:
        `v` - the vector to be added

    - #### add

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

      Parameters:
        `x` - x component of the vector
        `y` - y component of the vector
        `z` - z component of the vector

    - #### add

          public static PVector add(PVector v1,
                    PVector v2)

      Add two vectors
      Parameters:
        `v1` - a vector
        `v2` - another vector

    - #### add

          public static PVector add(PVector v1,
                    PVector v2,
                    PVector target)

      Add two vectors into a target vector
      Parameters:
        `target` - the target vector (if null, a new vector will be created)

    - #### sub

          public void sub(PVector v)

      ( begin auto-generated from PVector_sub.xml ) Subtracts x, y, and z components from a vector, subtracts one vector from another, or subtracts two independent vectors. The version of the method that subtracts two vectors is a static method and returns a PVector, the others have no return value -- they act directly on the vector. See the examples for more context. ( end auto-generated )
      Parameters:
        `v` - any variable of type PVector

    - #### sub

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

      Parameters:
        `x` - the x component of the vector
        `y` - the y component of the vector
        `z` - the z component of the vector

    - #### sub

          public static PVector sub(PVector v1,
                    PVector v2)

      Subtract one vector from another
      Parameters:
        `v1` - the x, y, and z components of a PVector object
        `v2` - the x, y, and z components of a PVector object

    - #### sub

          public static PVector sub(PVector v1,
                    PVector v2,
                    PVector target)

      Subtract one vector from another and store in another vector
      Parameters:
        `v1` - the x, y, and z components of a PVector object
        `v2` - the x, y, and z components of a PVector object
        `target` - PVector in which to store the result

    - #### mult

          public void mult(float n)

      ( begin auto-generated from PVector_mult.xml ) Multiplies a vector by a scalar or multiplies one vector by another. ( end auto-generated )
      Parameters:
        `n` - the number to multiply with the vector

    - #### mult

          public static PVector mult(PVector v,
                     float n)

      Parameters:
        `v` - the vector to multiply by the scalar

    - #### mult

          public static PVector mult(PVector v,
                     float n,
                     PVector target)

      Multiply a vector by a scalar, and write the result into a target PVector.
      Parameters:
        `target` - PVector in which to store the result

    - #### div

          public void div(float n)

      ( begin auto-generated from PVector_div.xml ) Divides a vector by a scalar or divides one vector by another. ( end auto-generated )
      Parameters:
        `n` - the number by which to divide the vector

    - #### div

          public static PVector div(PVector v,
                    float n)

      Divide a vector by a scalar and return the result in a new vector.
      Parameters:
        `v` - the vector to divide by the scalar
      Returns:
        a new vector that is v1 / n

    - #### div

          public static PVector div(PVector v,
                    float n,
                    PVector target)

      Divide a vector by a scalar and store the result in another vector.
      Parameters:
        `target` - PVector in which to store the result

    - #### dist

          public float dist(PVector v)

      ( begin auto-generated from PVector_dist.xml ) Calculates the Euclidean distance between two points (considering a point as a vector object). ( end auto-generated )
      Parameters:
        `v` - the x, y, and z coordinates of a PVector

    - #### dist

          public static float dist(PVector v1,
                   PVector v2)

      Parameters:
        `v1` - any variable of type PVector
        `v2` - any variable of type PVector
      Returns:
        the Euclidean distance between v1 and v2

    - #### dot

          public float dot(PVector v)

      ( begin auto-generated from PVector_dot.xml ) Calculates the dot product of two vectors. ( end auto-generated )
      Parameters:
        `v` - any variable of type PVector
      Returns:
        the dot product

    - #### dot

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

      Parameters:
        `x` - x component of the vector
        `y` - y component of the vector
        `z` - z component of the vector

    - #### dot

          public static float dot(PVector v1,
                  PVector v2)

      Parameters:
        `v1` - any variable of type PVector
        `v2` - any variable of type PVector

    - #### cross

          public PVector cross(PVector v)

      ( begin auto-generated from PVector_cross.xml ) Calculates and returns a vector composed of the cross product between two vectors. ( end auto-generated )
      Parameters:
        `v` - the vector to calculate the cross product

    - #### cross

          public PVector cross(PVector v,
                      PVector target)

      Parameters:
        `v` - any variable of type PVector
        `target` - PVector to store the result

    - #### cross

          public static PVector cross(PVector v1,
                      PVector v2,
                      PVector target)

      Parameters:
        `v1` - any variable of type PVector
        `v2` - any variable of type PVector
        `target` - PVector to store the result

    - #### normalize

          public void normalize()

      ( begin auto-generated from PVector_normalize.xml ) Normalize the vector to length 1 (make it a unit vector). ( end auto-generated )

    - #### normalize

          public PVector normalize(PVector target)

      Parameters:
        `target` - Set to null to create a new vector
      Returns:
        a new vector (if target was null), or target

    - #### limit

          public void limit(float max)

      ( begin auto-generated from PVector_limit.xml ) Limit the magnitude of this vector to the value used for the max parameter. ( end auto-generated )
      Parameters:
        `max` - the maximum magnitude for the vector

    - #### setMag

          public void setMag(float len)

      ( begin auto-generated from PVector_setMag.xml ) Set the magnitude of this vector to the value used for the len parameter. ( end auto-generated )
      Parameters:
        `len` - the new length for this vector

    - #### setMag

          public PVector setMag(PVector target,
                       float len)

      Sets the magnitude of this vector, storing the result in another vector.
      Parameters:
        `target` - Set to null to create a new vector
        `len` - the new length for the new vector
      Returns:
        a new vector (if target was null), or target

    - #### heading

          public float heading()

      ( begin auto-generated from PVector_setMag.xml ) Calculate the angle of rotation for this vector (only 2D vectors) ( end auto-generated )
      Returns:
        the angle of rotation

    - #### heading2D

          @Deprecated
          public float heading2D()

      Deprecated.

    - #### rotate

          public void rotate(float theta)

      ( begin auto-generated from PVector_rotate.xml ) Rotate the vector by an angle (only 2D vectors), magnitude remains the same ( end auto-generated )
      Parameters:
        `theta` - the angle of rotation

    - #### lerp

          public void lerp(PVector v,
                  float amt)

      ( begin auto-generated from PVector_rotate.xml ) Linear interpolate the vector to another vector ( end auto-generated )
      Parameters:
        `v` - the vector to lerp to
        `amt` - The amount of interpolation; some value between 0.0 (old vector) and 1.0 (new vector). 0.1 is very near the new vector. 0.5 is halfway in between.

    - #### lerp

          public static PVector lerp(PVector v1,
                     PVector v2,
                     float amt)

      Linear interpolate between two vectors (returns a new PVector object)
      Parameters:
        `v1` - the vector to start from
        `v2` - the vector to lerp to

    - #### lerp

          public void lerp(float x,
                  float y,
                  float z,
                  float amt)

      Linear interpolate the vector to x,y,z values
      Parameters:
        `x` - the x component to lerp to
        `y` - the y component to lerp to
        `z` - the z component to lerp to

    - #### angleBetween

          public static float angleBetween(PVector v1,
                           PVector v2)

      ( begin auto-generated from PVector_angleBetween.xml ) Calculates and returns the angle (in radians) between two vectors. ( end auto-generated )
      Parameters:
        `v1` - the x, y, and z components of a PVector
        `v2` - the x, y, and z components of a PVector

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### array

          public float[] array()

      ( begin auto-generated from PVector_array.xml ) Return a representation of this vector as a float array. This is only for temporary use. If used in any other fashion, the contents should be copied by using the PVector.get() method to copy into your own array. ( end auto-generated )

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`