public final class Vec2f extends Object
All methods return a new instance rather then modifying the object it self. A Vector is a quantity which has both magnitude and direction, but no position.
Null-HandlingPassing null values will cause to throw a NullpointerException. Methods which could throw a NullPointerException are marked in the javadoc.
Method namingof | static builder methods. starts the fluent pipeline |
is | performs a check, returns boolean and ends the fluent pipeline |
get | returns a component of this class and ends the fluent pipeline |
to | converts this object in another format and ends the fluent pipeline |
from | creates a instance using the specified input. starts the fluent pipeline |
* | all other methods which processes the instance and returns it for the fluent usage |
It is proposed to keep all vector classes immutable to prepare for Javas possible release of value types within project Valhalla. Vectors will be than value type based.
Modifier and Type | Field and Description |
---|---|
static byte |
BYTES
Defines how much bytes will be needed to store this type as binary
|
static int |
FIELDS
Defines how much fields are stored in this class which will be used for
optimal binary serialization
|
static Vec2f |
MAX
A vector with all coordinates set to the maximal value.
|
static Vec2f |
MIN
A vector with all coordinates set to the minimal value.
|
static Vec2f |
NAN
Represents the NAN vector
|
static Vec2f |
NEGATIVE_INFINITY
A vector with all coordinates set to negative infinity.
|
static Vec2f |
POSITIVE_INFINITY
A vector with all coordinates set to positive infinity.
|
static Vec2f |
XAXIS
Represents the X axis vector
|
static Vec2f |
YAXIS
Represents the Y axis vector
|
static Vec2f |
ZERO
Represents the zero vector
|
Constructor and Description |
---|
Vec2f(float amt)
Creates a new vector and sets all properties to the specified amount.
|
Vec2f(float x,
float y)
Creates a new vector for the specified properties
|
Modifier and Type | Method and Description |
---|---|
Vec2f |
absolute()
Computes the absolute number of each vector component and returns a new
vector.
|
Vec2f |
add(float amt)
Adds the current vector by the specified amount and returns a new one.
|
Vec2f |
add(Vec2f other)
Adds the current vector by the specified vector and returns a new one.
|
float |
angle(Vec2f v)
Return the angle between this vector and the supplied vector.
|
float |
angleCos(Vec2f v)
Return the cosine of the angle between this vector and the supplied
vector.
|
Vec2f |
ceil()
Ceils all values of the vector.
|
Vec2f |
clamp(float c)
Clamp all components to the constant c.
|
Vec2f |
clamp(Vec2f other)
Clamp all components to the ones from the specified vector.
|
float |
cross(Vec2f r)
Calculates the cross product between both specified vectors
A cross product is also an operation on two vectors.
|
Vec2f |
div(float amt)
Divides the current vector by the specified amount and returns a new one.
|
Vec2f |
div(Vec2f other)
Divides the current vector by the specified vector and returns a new one.
|
float |
dot(Vec2f other)
Calculates the dot product of this and the specified vector
This is one of, if not the most important operator(s) in geometry.
|
boolean |
equals(Object obj)
Determines whether or not two Vec3f points or vectors are equal.
|
Vec2f |
floor()
Floors all values of the vector.
|
static Vec2f |
fromBytes(byte[] data)
Converts the specified byte array (length >= 3) to a new vector
|
static Vec2f |
fromBytes(byte[] data,
int offset)
Converts the specified byte array (length >= 3) to a new vector by the
given offset
|
float |
getX() |
float |
getY() |
Vec2f |
half(Vec2f other)
Compute the half vector between this and the other vector.
|
int |
hashCode() |
boolean |
isInfinite()
Checks if any component has an infinite value.
|
boolean |
isNAN()
Checks if any component comprises the value NAN.
|
boolean |
isOppositeDirection(Vec2f vector)
Whether this vector has opposite direction compared to the other vector.
|
boolean |
isSameDirection(Vec2f vector)
Whether this vector has similar direction compared to the other vector.
|
boolean |
isUnit()
Checks if this vector is a unit one where the total length is 1.
|
boolean |
isValid()
Checks this vector if it is null or its floats are NaN or infinite,
return false.
|
boolean |
isZero()
Checks if this vector bellows to a zero one (all components are zero).
|
float |
length()
Calculates the regular length or magnitude of this vector.
|
float |
lengthEuclidean(Vec2f r)
Calculates the Euclidean (ordinalry) distance between this and the other
vector.
|
float |
lengthManhattan(Vec2f r)
Calculates the Manhattan length between two vectors.
|
float |
lengthManhattan(Vec2f r,
float unit)
Calculates the Manhattan length between two vectors for a specified unit.
|
float |
lengthSquared()
Calculates the squared length or magnitude of this vector.
|
Vec2f |
lerp(Vec2f dest,
float amt)
Linearly interpolates between this vector and the target vector by alpha
which is in the range [0,1].
|
Mat4f |
mat4Rotation()
Swizzling this Vector to a 4x4 matrix where the coordinates are stored in
the rotation view of the matrix.
|
Mat4f |
mat4Scale()
Swizzling this Vector to a 4x4 matrix where the coordinates are stored in
the scale view of the matrix.
|
Mat4f |
mat4Translation()
Swizzling this Vector to a 4x4 matrix where the coordinates are stored in
the translation view of the matrix.
|
float |
max()
Returns the max value of the vector components
|
Vec2f |
max(Vec2f other)
Returns the max vector between this and the specified one.
|
float |
min()
Returns the minimal value of the vector components
|
Vec2f |
min(Vec2f other)
Returns the minimal vector between this and the specified one.
|
Vec2f |
mul(float amt)
Multiplies the current vector by the specified amount and returns a new
one.
|
Vec2f |
mul(Vec2f other)
Multiplies the current vector by the specified vector and returns a new
one.
|
Vec2f |
negate()
Negates all components of this vector.
|
Vec2f |
normalize()
Normalizes this vector
It is sometimes useful to express vectors only by their direction and not
by their length.
|
static Vec2f |
of(float amt)
Creates an new Vec3f instance where each component has the specified
amount.
|
static Vec2f |
of(float x,
float y)
Creates an new Vec3f instance where each component has the specified
float.
|
Vec2f |
project(Vec2f other)
Projects this vector onto another vector.
|
Quatf |
quat()
Swizzling this Vector down to a Quaternion where w component is zero.
|
Quatf |
quat(float w)
Swizzling this Vector to a Quaternion where w component is the specified
one.
|
Vec2f |
reflect(Vec2f normal)
Reflect this vector about the given normal vector.
|
Vec2f |
sub(float amt)
Subtracts the current vector by the specified amount and returns a new
one.
|
Vec2f |
sub(Vec2f other)
Subtracts the current vector by the specified vector and returns a new
one.
|
byte[] |
toBytes()
Converts the vector to a byte array optimized for high performance
serialization.
|
byte[] |
toBytes(byte[] data)
Converts the vector to the specified byte array optimized for high
performance serialization.
|
byte[] |
toBytes(byte[] data,
int offset)
Converts the vector to the specified byte array optimized for high
performance serialization.
|
String |
toString() |
Vec4f |
vec4()
Swizzling this Vector to a 4 dimensional one where the z and w component
is zero.
|
Vec4f |
vec4(float w)
Swizzling this Vector to a 4 dimensional one where the w component is the
specfied one.
|
Vec1f |
x()
Swizzling this Vector down to another.
|
Vec1f |
y()
Swizzling this Vector down to another.
|
public static final int FIELDS
public static final byte BYTES
public static final Vec2f XAXIS
public static final Vec2f YAXIS
public static final Vec2f ZERO
public static final Vec2f NAN
public static final Vec2f POSITIVE_INFINITY
public static final Vec2f NEGATIVE_INFINITY
public static final Vec2f MIN
public static final Vec2f MAX
public Vec2f(float amt)
amt
- as the value for x and ypublic Vec2f(float x, float y)
x
- the x componenty
- the y componentpublic static Vec2f of(float amt)
amt
- to apply to all componentspublic static Vec2f of(float x, float y)
x
- the x componenty
- the y componentpublic float length()
public float lengthSquared()
public float lengthManhattan(Vec2f r, float unit)
The Manhattan length (aka. Taxicab geometry) calculates the distance between two vectors in a real vector space with fixed cartesian coordinate systems and is the sum of the lengths of the projections of the line between the points onto the coordinate axis.
In other words the distance between two vectors in the euclidean space would be a direct line from start point toward the end point while the Manhattan length is bound to the aligned axis (like x,y or z).
r
- the end point from the current start vectorunit
- the calculation unit length for the fixed axis length.
Normally 1.0f is set. 0.5f will double the Manhattan length
result.NullPointerException
- if passed vector r is nullDefault Manhattan length calculation
,
lengthEuclidean(Vec2f)
public float lengthManhattan(Vec2f r)
The Manhattan length (aka. Taxicab geometry) calculates the distance between two vectors in a real vector space with fixed cartesian coordinate systems and is the sum of the lengths of the projections of the line between the points onto the coordinate axis.
In other words the distance between two vectors in the euclidean space would be a direct line from start point toward the end point while the Manhattan length is bound to the aligned axis (like x,y or z).
r
- the end point from the current start vectorNullPointerException
- if passed vector r is nullPassing a unit value to
Manhattan length calculation
,
lengthEuclidean(Vec2f)
public float lengthEuclidean(Vec2f r)
Calculates the euclidean distance in the "ordinary" distance between two points in the euclidean space. With this distance the euclidean space is mapped to the matrix space (aka. euclidean norm).
In other words the distance between two vectors in the Manhattan length is bound to the aligned axis (like x,y or z) while the euclidean space would be a direct line from start point toward the end point.
r
- the other vectorlengthManhattan(Vec2f)
public float dot(Vec2f other)
This is one of, if not the most important operator(s) in geometry. Its so important because it gets used for many tasks, such as projecting a vector along another, or to help in finding the magnitude of a vector. It works consistently in any number of dimensions (unlike the cross product, which is only defined in 3d).
The dot product of two vectors is equal to the magnitude of each multiplied together all multiplied by the cosine of the angle between them
So when two unit vectors point exactly the same way, the result of the dot product is 1 and when they are exactly opposite -1. The dot product returns 0 for any two vectors (unit or otherwise) at 90o to each other in some plane.
The really useful part comes when we realize that this geometric description also allows us to tell how much of a vector is in the direction of another, because when we know that we can calculate this new projected vector which is useful in all sorts of geometric problems, rotation being one of the most fundamental.
other
- the other for dot product calculationpublic float min()
public Vec2f min(Vec2f other)
other
- the other vectorpublic float max()
public Vec2f max(Vec2f other)
other
- the other vectorpublic Vec2f ceil()
public Vec2f floor()
public Vec2f absolute()
public Vec2f negate()
public Vec2f clamp(float c)
c
- the clamp value to comparepublic Vec2f clamp(Vec2f other)
other
- the clamp vector to compareNullPointerException
- if the passed vector is nullpublic boolean isUnit()
A unit vector is simply a vector whose length (or magnitude) is 1. These are extremely important in geometry because they allow transformations which do not alter the scale of the things being transformed. Such a vector is said to be normalized - i.e. divided by its length:
public boolean isZero()
public boolean isNAN()
public boolean isInfinite()
public boolean isSameDirection(Vec2f vector)
vector
- the other vector to checkNullPointerException
- if the passed vector is nullpublic boolean isOppositeDirection(Vec2f vector)
vector
- the other vector to checkNullPointerException
- if the passed vector is nullpublic boolean isValid()
public float angleCos(Vec2f v)
v
- the other vectorNullPointerException
- if the passed vector is nullpublic float angle(Vec2f v)
v
- NullPointerException
- if the passed vector is nullpublic Vec2f normalize()
It is sometimes useful to express vectors only by their direction and not by their length. This is necessary for example when we want to find out if another object, or point is in front of or behind our reference frame, or when we need to calculate a reflection vector that would occur from a surface with a “upward facing plane”. Vectors of unit length are also called normals.
Example for a normalized vector between one(1,1) and two(-1,-1):^ two(-1,-1) | one(1,1) \ | / \|/ 0 normalized
In words, the normalized vector is the vector divided by the magnitude of itself. This results in a vector of unit length. We must take care when calculating the normalized vector because zero length vectors cannot be normalized. Normalizing a zero-length vector will usually result in a “divide-by-zero” error. Usually we resolve this by performing the normalization in multiple steps:
This example shows you how to calculate the normal vector based on two
"origin" vectors. This technique for example is used when a model from
formats like "obj" are imported and we want to calculate the normal
vectors.
Vec3f vectorOne = ...
Vec3f vectorTwo = ...
Vec3f normalVector = vectorOne.cross(vectorTwo).normalize();
public float cross(Vec2f r)
A cross product is also an operation on two vectors. The result is a third vector, which is perpendicular to the first two, and it's length is an average of the both lengths.
Note that for cross product, the order of arguments matters. If you switch order, the result will be a vector of the same length, but facing the opposite direction.
r
- the other vectorNullPointerException
- if the passed vector is nullpublic Vec2f project(Vec2f other)
What is projection? It is the procedure of taking something in n dimensions and collapsing it down to the dimension below (n-1). So in 3d rendering we often want to project the 3d world onto the near plane of the camera. When we do a dot product we are projecting one vector onto another and the by product is a scalar.
other
- the other vector for projectionNullPointerException
- if the passed vector is nullpublic Vec2f reflect(Vec2f normal)
normal
- the vector to reflect aboutNullPointerException
- if the passed normal vector is nullpublic Vec2f half(Vec2f other)
other
- NullPointerException
- if the passed vector is nullpublic Vec2f lerp(Vec2f dest, float amt)
dest
- the target vectoramt
- the interpolation coefficient in the range [0,1]NullPointerException
- if the passed destination vector is nullpublic Vec2f add(Vec2f other)
other
- vector amount of the additionNullPointerException
- if the passed vector is nullpublic Vec2f add(float amt)
amt
- amount of the additionpublic Vec2f sub(Vec2f other)
other
- vector amount of the subtractionNullPointerException
- if the passed vector is nullpublic Vec2f sub(float amt)
amt
- amount of the subtractionpublic Vec2f mul(Vec2f other)
other
- vector amount of the multiplicationNullPointerException
- if the passed vector is nullpublic Vec2f mul(float amt)
amt
- amount of the multiplicationpublic Vec2f div(Vec2f other)
other
- vector amount of the divisionNullPointerException
- if the passed vector is nullpublic Vec2f div(float amt)
amt
- amount of the divisionpublic Vec1f x()
public Vec1f y()
public Quatf quat()
public Quatf quat(float w)
w
- as w component of the quaternionpublic Mat4f mat4Translation()
public Mat4f mat4Scale()
public Mat4f mat4Rotation()
public Vec4f vec4()
public Vec4f vec4(float w)
w
- the component of w for the new vectorpublic float getX()
public float getY()
public byte[] toBytes()
public byte[] toBytes(byte[] data)
data
- the array to store the datapublic byte[] toBytes(byte[] data, int offset)
data
- the array to store the dataoffset
- the offset to start frompublic static Vec2f fromBytes(byte[] data)
data
- the byte data (0=X,1=Y,2=Z)public static Vec2f fromBytes(byte[] data, int offset)
data
- the byte data (0=X,1=Y,2=Z)offset
- public boolean equals(Object obj)
Vec3f
are equal if the values of their
x
, y
and z
member fields,
representing their position in the coordinate space, are the same.Copyright © 2017–2018. All rights reserved.