org.joml.Quaternionfc Maven / Gradle / Ivy
/*
* The MIT License
*
* Copyright (c) 2015-2020 JOML
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package org.joml;
import java.nio.ByteBuffer;
import java.nio.FloatBuffer;
/**
* Interface to a read-only view of a quaternion of single-precision floats.
*
* @author Kai Burjack
*/
public interface Quaternionfc {
/**
* @return the first component of the vector part
*/
float x();
/**
* @return the second component of the vector part
*/
float y();
/**
* @return the third component of the vector part
*/
float z();
/**
* @return the real/scalar part of the quaternion
*/
float w();
/**
* Normalize this quaternion and store the result in dest.
*
* @param dest
* will hold the result
* @return dest
*/
Quaternionf normalize(Quaternionf dest);
/**
* Add the quaternion (x, y, z, w) to this quaternion and store the result in dest.
*
* @param x
* the x component of the vector part
* @param y
* the y component of the vector part
* @param z
* the z component of the vector part
* @param w
* the real/scalar component
* @param dest
* will hold the result
* @return dest
*/
Quaternionf add(float x, float y, float z, float w, Quaternionf dest);
/**
* Add q2 to this quaternion and store the result in dest.
*
* @param q2
* the quaternion to add to this
* @param dest
* will hold the result
* @return dest
*/
Quaternionf add(Quaternionfc q2, Quaternionf dest);
/**
* Return the angle in radians represented by this normalized quaternion rotation.
*
* This quaternion must be {@link #normalize(Quaternionf) normalized}.
*
* @return the angle in radians
*/
float angle();
/**
* Set the given destination matrix to the rotation represented by this.
*
* @see Matrix3f#set(Quaternionfc)
*
* @param dest
* the matrix to write the rotation into
* @return the passed in destination
*/
Matrix3f get(Matrix3f dest);
/**
* Set the given destination matrix to the rotation represented by this.
*
* @see Matrix3d#set(Quaternionfc)
*
* @param dest
* the matrix to write the rotation into
* @return the passed in destination
*/
Matrix3d get(Matrix3d dest);
/**
* Set the given destination matrix to the rotation represented by this.
*
* @see Matrix4f#set(Quaternionfc)
*
* @param dest
* the matrix to write the rotation into
* @return the passed in destination
*/
Matrix4f get(Matrix4f dest);
/**
* Set the given destination matrix to the rotation represented by this.
*
* @see Matrix4d#set(Quaternionfc)
*
* @param dest
* the matrix to write the rotation into
* @return the passed in destination
*/
Matrix4d get(Matrix4d dest);
/**
* Set the given destination matrix to the rotation represented by this.
*
* @see Matrix4x3f#set(Quaternionfc)
*
* @param dest
* the matrix to write the rotation into
* @return the passed in destination
*/
Matrix4x3f get(Matrix4x3f dest);
/**
* Set the given destination matrix to the rotation represented by this.
*
* @see Matrix4x3d#set(Quaternionfc)
*
* @param dest
* the matrix to write the rotation into
* @return the passed in destination
*/
Matrix4x3d get(Matrix4x3d dest);
/**
* Set the given {@link AxisAngle4f} to represent the rotation of
* this quaternion.
*
* @param dest
* the {@link AxisAngle4f} to set
* @return the passed in destination
*/
AxisAngle4f get(AxisAngle4f dest);
/**
* Set the given {@link AxisAngle4d} to represent the rotation of
* this quaternion.
*
* @param dest
* the {@link AxisAngle4d} to set
* @return the passed in destination
*/
AxisAngle4d get(AxisAngle4d dest);
/**
* Set the given {@link Quaterniond} to the values of this.
*
* @see Quaterniond#set(Quaternionfc)
*
* @param dest
* the {@link Quaterniond} to set
* @return the passed in destination
*/
Quaterniond get(Quaterniond dest);
/**
* Set the given {@link Quaternionf} to the values of this.
*
* @param dest
* the {@link Quaternionf} to set
* @return the passed in destination
*/
Quaternionf get(Quaternionf dest);
/**
* Store the 3x3 float matrix representation of this quaternion in column-major order into the given {@link ByteBuffer}.
*
* This is equivalent to calling: this.get(new Matrix3f()).get(dest)
*
* @param dest
* the destination buffer
* @return dest
*/
ByteBuffer getAsMatrix3f(ByteBuffer dest);
/**
* Store the 3x3 float matrix representation of this quaternion in column-major order into the given {@link FloatBuffer}.
*
* This is equivalent to calling: this.get(new Matrix3f()).get(dest)
*
* @param dest
* the destination buffer
* @return dest
*/
FloatBuffer getAsMatrix3f(FloatBuffer dest);
/**
* Store the 4x4 float matrix representation of this quaternion in column-major order into the given {@link ByteBuffer}.
*
* This is equivalent to calling: this.get(new Matrix4f()).get(dest)
*
* @param dest
* the destination buffer
* @return dest
*/
ByteBuffer getAsMatrix4f(ByteBuffer dest);
/**
* Store the 4x4 float matrix representation of this quaternion in column-major order into the given {@link FloatBuffer}.
*
* This is equivalent to calling: this.get(new Matrix4f()).get(dest)
*
* @param dest
* the destination buffer
* @return dest
*/
FloatBuffer getAsMatrix4f(FloatBuffer dest);
/**
* Store the 4x3 float matrix representation of this quaternion in column-major order into the given {@link ByteBuffer}.
*
* This is equivalent to calling: this.get(new Matrix4x3f()).get(dest)
*
* @param dest
* the destination buffer
* @return dest
*/
ByteBuffer getAsMatrix4x3f(ByteBuffer dest);
/**
* Store the 4x3 float matrix representation of this quaternion in column-major order into the given {@link FloatBuffer}.
*
* This is equivalent to calling: this.get(new Matrix4x3f()).get(dest)
*
* @param dest
* the destination buffer
* @return dest
*/
FloatBuffer getAsMatrix4x3f(FloatBuffer dest);
/**
* Multiply this quaternion by q and store the result in dest.
*
* If T is this and Q is the given
* quaternion, then the resulting quaternion R is:
*
* R = T * Q
*
* So, this method uses post-multiplication like the matrix classes, resulting in a
* vector to be transformed by Q first, and then by T.
*
* @param q
* the quaternion to multiply this by
* @param dest
* will hold the result
* @return dest
*/
Quaternionf mul(Quaternionfc q, Quaternionf dest);
/**
* Multiply this quaternion by the quaternion represented via (qx, qy, qz, qw) and store the result in dest.
*
* If T is this and Q is the given
* quaternion, then the resulting quaternion R is:
*
* R = T * Q
*
* So, this method uses post-multiplication like the matrix classes, resulting in a
* vector to be transformed by Q first, and then by T.
*
* @param qx
* the x component of the quaternion to multiply this by
* @param qy
* the y component of the quaternion to multiply this by
* @param qz
* the z component of the quaternion to multiply this by
* @param qw
* the w component of the quaternion to multiply this by
* @param dest
* will hold the result
* @return dest
*/
Quaternionf mul(float qx, float qy, float qz, float qw, Quaternionf dest);
/**
* Pre-multiply this quaternion by q and store the result in dest.
*
* If T is this and Q is the given quaternion, then the resulting quaternion R is:
*
* R = Q * T
*
* So, this method uses pre-multiplication, resulting in a vector to be transformed by T first, and then by Q.
*
* @param q
* the quaternion to pre-multiply this by
* @param dest
* will hold the result
* @return dest
*/
Quaternionf premul(Quaternionfc q, Quaternionf dest);
/**
* Pre-multiply this quaternion by the quaternion represented via (qx, qy, qz, qw) and store the result in dest.
*
* If T is this and Q is the given quaternion, then the resulting quaternion R is:
*
* R = Q * T
*
* So, this method uses pre-multiplication, resulting in a vector to be transformed by T first, and then by Q.
*
* @param qx
* the x component of the quaternion to multiply this by
* @param qy
* the y component of the quaternion to multiply this by
* @param qz
* the z component of the quaternion to multiply this by
* @param qw
* the w component of the quaternion to multiply this by
* @param dest
* will hold the result
* @return dest
*/
Quaternionf premul(float qx, float qy, float qz, float qw, Quaternionf dest);
/**
* Transform the given vector by this quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector3f transform(Vector3f vec);
/**
* Transform the given vector by this unit quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector3f transformUnit(Vector3f vec);
/**
* Transform the vector (1, 0, 0) by this quaternion.
*
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformPositiveX(Vector3f dest);
/**
* Transform the vector (1, 0, 0) by this quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformPositiveX(Vector4f dest);
/**
* Transform the vector (1, 0, 0) by this unit quaternion.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformUnitPositiveX(Vector3f dest);
/**
* Transform the vector (1, 0, 0) by this unit quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformUnitPositiveX(Vector4f dest);
/**
* Transform the vector (0, 1, 0) by this quaternion.
*
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformPositiveY(Vector3f dest);
/**
* Transform the vector (0, 1, 0) by this quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformPositiveY(Vector4f dest);
/**
* Transform the vector (0, 1, 0) by this unit quaternion.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformUnitPositiveY(Vector3f dest);
/**
* Transform the vector (0, 1, 0) by this unit quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformUnitPositiveY(Vector4f dest);
/**
* Transform the vector (0, 0, 1) by this quaternion.
*
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformPositiveZ(Vector3f dest);
/**
* Transform the vector (0, 0, 1) by this quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformPositiveZ(Vector4f dest);
/**
* Transform the vector (0, 0, 1) by this unit quaternion.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformUnitPositiveZ(Vector3f dest);
/**
* Transform the vector (0, 0, 1) by this unit quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformUnitPositiveZ(Vector4f dest);
/**
* Transform the given vector by this quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and modified.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector4f transform(Vector4f vec);
/**
* Transform the given vector by the inverse of this quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and modified.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector4f transformInverse(Vector4f vec);
/**
* Transform the given vector by this quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transform(Vector3fc vec, Vector3f dest);
/**
* Transform the given vector by the inverse of quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformInverse(Vector3fc vec, Vector3f dest);
/**
* Transform the given vector (x, y, z) by this quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transform(float x, float y, float z, Vector3f dest);
/**
* Transform the given vector (x, y, z) by the inverse of this quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformInverse(float x, float y, float z, Vector3f dest);
/**
* Transform the given vector by this unit quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformUnit(Vector3fc vec, Vector3f dest);
/**
* Transform the given vector by the inverse of this unit quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformInverseUnit(Vector3fc vec, Vector3f dest);
/**
* Transform the given vector (x, y, z) by this unit quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformUnit(float x, float y, float z, Vector3f dest);
/**
* Transform the given vector (x, y, z) by the inverse of this unit quaternion
* and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3f transformInverseUnit(float x, float y, float z, Vector3f dest);
/**
* Transform the given vector by this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transform(Vector4fc vec, Vector4f dest);
/**
* Transform the given vector by the inverse of this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformInverse(Vector4fc vec, Vector4f dest);
/**
* Transform the given vector (x, y, z) by this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transform(float x, float y, float z, Vector4f dest);
/**
* Transform the given vector (x, y, z) by the inverse of
* this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformInverse(float x, float y, float z, Vector4f dest);
/**
* Transform the given vector by this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformUnit(Vector4fc vec, Vector4f dest);
/**
* Transform the given vector by the inverse of this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformInverseUnit(Vector4fc vec, Vector4f dest);
/**
* Transform the given vector (x, y, z) by this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformUnit(float x, float y, float z, Vector4f dest);
/**
* Transform the given vector (x, y, z) by the inverse of
* this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4f transformInverseUnit(float x, float y, float z, Vector4f dest);
/**
* Transform the given vector by this quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector3d transform(Vector3d vec);
/**
* Transform the given vector by the inverse of this quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector3d transformInverse(Vector3d vec);
/**
* Transform the vector (1, 0, 0) by this quaternion.
*
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformPositiveX(Vector3d dest);
/**
* Transform the vector (1, 0, 0) by this quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformPositiveX(Vector4d dest);
/**
* Transform the vector (1, 0, 0) by this unit quaternion.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformUnitPositiveX(Vector3d dest);
/**
* Transform the vector (1, 0, 0) by this unit quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformUnitPositiveX(Vector4d dest);
/**
* Transform the vector (0, 1, 0) by this quaternion.
*
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformPositiveY(Vector3d dest);
/**
* Transform the vector (0, 1, 0) by this quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformPositiveY(Vector4d dest);
/**
* Transform the vector (0, 1, 0) by this unit quaternion.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformUnitPositiveY(Vector3d dest);
/**
* Transform the vector (0, 1, 0) by this unit quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformUnitPositiveY(Vector4d dest);
/**
* Transform the vector (0, 0, 1) by this quaternion.
*
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformPositiveZ(Vector3d dest);
/**
* Transform the vector (0, 0, 1) by this quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformPositiveZ(Vector4d dest);
/**
* Transform the vector (0, 0, 1) by this unit quaternion.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformUnitPositiveZ(Vector3d dest);
/**
* Transform the vector (0, 0, 1) by this unit quaternion.
*
* Only the first three components of the given 4D vector are modified.
*
* This method is only applicable when this is a unit quaternion.
*
* Reference: https://de.mathworks.com/
*
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformUnitPositiveZ(Vector4d dest);
/**
* Transform the given vector by this quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and modified.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector4d transform(Vector4d vec);
/**
* Transform the given vector by the inverse of this quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and modified.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector4d transformInverse(Vector4d vec);
/**
* Transform the given vector by this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transform(Vector3dc vec, Vector3d dest);
/**
* Transform the given vector by the inverse of this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformInverse(Vector3dc vec, Vector3d dest);
/**
* Transform the given vector (x, y, z) by this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transform(double x, double y, double z, Vector3d dest);
/**
* Transform the given vector (x, y, z) by the inverse of
* this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformInverse(double x, double y, double z, Vector3d dest);
/**
* Transform the given vector by this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transform(Vector4dc vec, Vector4d dest);
/**
* Transform the given vector by the inverse of this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformInverse(Vector4dc vec, Vector4d dest);
/**
* Transform the given vector (x, y, z) by this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transform(double x, double y, double z, Vector4d dest);
/**
* Transform the given vector (x, y, z) by the inverse of
* this quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformInverse(double x, double y, double z, Vector4d dest);
/**
* Transform the given vector by this unit quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and modified.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector4d transformUnit(Vector4d vec);
/**
* Transform the given vector by the inverse of this unit quaternion.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and modified.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @return vec
*/
Vector4d transformInverseUnit(Vector4d vec);
/**
* Transform the given vector by this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformUnit(Vector3dc vec, Vector3d dest);
/**
* Transform the given vector by the inverse of this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformInverseUnit(Vector3dc vec, Vector3d dest);
/**
* Transform the given vector (x, y, z) by this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformUnit(double x, double y, double z, Vector3d dest);
/**
* Transform the given vector (x, y, z) by the inverse of
* this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector3d transformInverseUnit(double x, double y, double z, Vector3d dest);
/**
* Transform the given vector by this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformUnit(Vector4dc vec, Vector4d dest);
/**
* Transform the given vector by the inverse of this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* Only the first three components of the given 4D vector are being used and set on the destination.
*
* This method is only applicable when this is a unit quaternion.
*
* @param vec
* the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformInverseUnit(Vector4dc vec, Vector4d dest);
/**
* Transform the given vector (x, y, z) by this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformUnit(double x, double y, double z, Vector4d dest);
/**
* Transform the given vector (x, y, z) by the inverse of
* this unit quaternion and store the result in dest.
*
* This will apply the rotation described by this quaternion to the given vector.
*
* This method is only applicable when this is a unit quaternion.
*
* @param x
* the x coordinate of the vector to transform
* @param y
* the y coordinate of the vector to transform
* @param z
* the z coordinate of the vector to transform
* @param dest
* will hold the result
* @return dest
*/
Vector4d transformInverseUnit(double x, double y, double z, Vector4d dest);
/**
* Invert this quaternion and store the {@link #normalize(Quaternionf) normalized} result in dest.
*
* If this quaternion is already normalized, then {@link #conjugate(Quaternionf)} should be used instead.
*
* @see #conjugate(Quaternionf)
*
* @param dest
* will hold the result
* @return dest
*/
Quaternionf invert(Quaternionf dest);
/**
* Divide this quaternion by b and store the result in dest.
*
* The division expressed using the inverse is performed in the following way:
*
* dest = this * b^-1, where b^-1 is the inverse of b.
*
* @param b
* the {@link Quaternionfc} to divide this by
* @param dest
* will hold the result
* @return dest
*/
Quaternionf div(Quaternionfc b, Quaternionf dest);
/**
* Conjugate this quaternion and store the result in dest.
*
* @param dest
* will hold the result
* @return dest
*/
Quaternionf conjugate(Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the cartesian base unit axes,
* called the euler angles using rotation sequence XYZ and store the result in dest.
*
* This method is equivalent to calling: rotateX(angleX, dest).rotateY(angleY).rotateZ(angleZ)
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @param angleX
* the angle in radians to rotate about the x axis
* @param angleY
* the angle in radians to rotate about the y axis
* @param angleZ
* the angle in radians to rotate about the z axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateXYZ(float angleX, float angleY, float angleZ, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the cartesian base unit axes,
* called the euler angles, using the rotation sequence ZYX and store the result in dest.
*
* This method is equivalent to calling: rotateZ(angleZ, dest).rotateY(angleY).rotateX(angleX)
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @param angleZ
* the angle in radians to rotate about the z axis
* @param angleY
* the angle in radians to rotate about the y axis
* @param angleX
* the angle in radians to rotate about the x axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateZYX(float angleZ, float angleY, float angleX, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the cartesian base unit axes,
* called the euler angles, using the rotation sequence YXZ and store the result in dest.
*
* This method is equivalent to calling: rotateY(angleY, dest).rotateX(angleX).rotateZ(angleZ)
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @param angleY
* the angle in radians to rotate about the y axis
* @param angleX
* the angle in radians to rotate about the x axis
* @param angleZ
* the angle in radians to rotate about the z axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateYXZ(float angleY, float angleX, float angleZ, Quaternionf dest);
/**
* Get the euler angles in radians in rotation sequence XYZ of this quaternion and store them in the
* provided parameter eulerAngles.
*
* @param eulerAngles
* will hold the euler angles in radians
* @return the passed in vector
*/
Vector3f getEulerAnglesXYZ(Vector3f eulerAngles);
/**
* Return the square of the length of this quaternion.
*
* @return the length
*/
float lengthSquared();
/**
* Interpolate between this {@link #normalize(Quaternionf) unit} quaternion and the specified
* target {@link #normalize(Quaternionf) unit} quaternion using spherical linear interpolation using the specified interpolation factor alpha,
* and store the result in dest.
*
* This method resorts to non-spherical linear interpolation when the absolute dot product of this and target is
* below 1E-6f.
*
* Reference: http://fabiensanglard.net
*
* @param target
* the target of the interpolation, which should be reached with alpha = 1.0
* @param alpha
* the interpolation factor, within [0..1]
* @param dest
* will hold the result
* @return dest
*/
Quaternionf slerp(Quaternionfc target, float alpha, Quaternionf dest);
/**
* Apply scaling to this quaternion, which results in any vector transformed by the quaternion to change
* its length by the given factor, and store the result in dest.
*
* @param factor
* the scaling factor
* @param dest
* will hold the result
* @return dest
*/
Quaternionf scale(float factor, Quaternionf dest);
/**
* Integrate the rotation given by the angular velocity (vx, vy, vz) around the x, y and z axis, respectively,
* with respect to the given elapsed time delta dt and add the differentiate rotation to the rotation represented by this quaternion
* and store the result into dest.
*
* This method pre-multiplies the rotation given by dt and (vx, vy, vz) by this, so
* the angular velocities are always relative to the local coordinate system of the rotation represented by this quaternion.
*
* This method is equivalent to calling: rotateLocal(dt * vx, dt * vy, dt * vz, dest)
*
* Reference: http://physicsforgames.blogspot.de/
*
* @param dt
* the delta time
* @param vx
* the angular velocity around the x axis
* @param vy
* the angular velocity around the y axis
* @param vz
* the angular velocity around the z axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf integrate(float dt, float vx, float vy, float vz, Quaternionf dest);
/**
* Compute a linear (non-spherical) interpolation of this and the given quaternion q
* and store the result in dest.
*
* Reference: http://fabiensanglard.net
*
* @param q
* the other quaternion
* @param factor
* the interpolation factor. It is between 0.0 and 1.0
* @param dest
* will hold the result
* @return dest
*/
Quaternionf nlerp(Quaternionfc q, float factor, Quaternionf dest);
/**
* Compute linear (non-spherical) interpolations of this and the given quaternion q
* iteratively and store the result in dest.
*
* This method performs a series of small-step nlerp interpolations to avoid doing a costly spherical linear interpolation, like
* {@link #slerp(Quaternionfc, float, Quaternionf) slerp},
* by subdividing the rotation arc between this and q via non-spherical linear interpolations as long as
* the absolute dot product of this and q is greater than the given dotThreshold parameter.
*
* Thanks to @theagentd at http://www.java-gaming.org/ for providing the code.
*
* @param q
* the other quaternion
* @param alpha
* the interpolation factor, between 0.0 and 1.0
* @param dotThreshold
* the threshold for the dot product of this and q above which this method performs another iteration
* of a small-step linear interpolation
* @param dest
* will hold the result
* @return dest
*/
Quaternionf nlerpIterative(Quaternionfc q, float alpha, float dotThreshold, Quaternionf dest);
/**
* Apply a rotation to this quaternion that maps the given direction to the positive Z axis, and store the result in dest.
*
* Because there are multiple possibilities for such a rotation, this method will choose the one that ensures the given up direction to remain
* parallel to the plane spanned by the up and dir vectors.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* Reference: http://answers.unity3d.com
*
* @see #lookAlong(float, float, float, float, float, float, Quaternionf)
*
* @param dir
* the direction to map to the positive Z axis
* @param up
* the vector which will be mapped to a vector parallel to the plane
* spanned by the given dir and up
* @param dest
* will hold the result
* @return dest
*/
Quaternionf lookAlong(Vector3fc dir, Vector3fc up, Quaternionf dest);
/**
* Apply a rotation to this quaternion that maps the given direction to the positive Z axis, and store the result in dest.
*
* Because there are multiple possibilities for such a rotation, this method will choose the one that ensures the given up direction to remain
* parallel to the plane spanned by the up and dir vectors.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* Reference: http://answers.unity3d.com
*
* @param dirX
* the x-coordinate of the direction to look along
* @param dirY
* the y-coordinate of the direction to look along
* @param dirZ
* the z-coordinate of the direction to look along
* @param upX
* the x-coordinate of the up vector
* @param upY
* the y-coordinate of the up vector
* @param upZ
* the z-coordinate of the up vector
* @param dest
* will hold the result
* @return dest
*/
Quaternionf lookAlong(float dirX, float dirY, float dirZ, float upX, float upY, float upZ, Quaternionf dest);
/**
* Apply a rotation to this that rotates the fromDir vector to point along toDir and
* store the result in dest.
*
* Since there can be multiple possible rotations, this method chooses the one with the shortest arc.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* Reference: stackoverflow.com
*
* @param fromDirX
* the x-coordinate of the direction to rotate into the destination direction
* @param fromDirY
* the y-coordinate of the direction to rotate into the destination direction
* @param fromDirZ
* the z-coordinate of the direction to rotate into the destination direction
* @param toDirX
* the x-coordinate of the direction to rotate to
* @param toDirY
* the y-coordinate of the direction to rotate to
* @param toDirZ
* the z-coordinate of the direction to rotate to
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateTo(float fromDirX, float fromDirY, float fromDirZ, float toDirX, float toDirY, float toDirZ, Quaternionf dest);
/**
* Apply a rotation to this that rotates the fromDir vector to point along toDir and
* store the result in dest.
*
* Because there can be multiple possible rotations, this method chooses the one with the shortest arc.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @see #rotateTo(float, float, float, float, float, float, Quaternionf)
*
* @param fromDir
* the starting direction
* @param toDir
* the destination direction
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateTo(Vector3fc fromDir, Vector3fc toDir, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the x axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @param angle
* the angle in radians to rotate about the x axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateX(float angle, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the y axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @param angle
* the angle in radians to rotate about the y axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateY(float angle, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the z axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @param angle
* the angle in radians to rotate about the z axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateZ(float angle, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the local x axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be R * Q. So when transforming a
* vector v with the new quaternion by using R * Q * v, the
* rotation represented by this will be applied first!
*
* @param angle
* the angle in radians to rotate about the local x axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateLocalX(float angle, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the local y axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be R * Q. So when transforming a
* vector v with the new quaternion by using R * Q * v, the
* rotation represented by this will be applied first!
*
* @param angle
* the angle in radians to rotate about the local y axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateLocalY(float angle, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the local z axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be R * Q. So when transforming a
* vector v with the new quaternion by using R * Q * v, the
* rotation represented by this will be applied first!
*
* @param angle
* the angle in radians to rotate about the local z axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateLocalZ(float angle, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the specified axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @param angle
* the angle in radians to rotate about the specified axis
* @param axisX
* the x coordinate of the rotation axis
* @param axisY
* the y coordinate of the rotation axis
* @param axisZ
* the z coordinate of the rotation axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateAxis(float angle, float axisX, float axisY, float axisZ, Quaternionf dest);
/**
* Apply a rotation to this quaternion rotating the given radians about the specified axis
* and store the result in dest.
*
* If Q is this quaternion and R the quaternion representing the
* specified rotation, then the new quaternion will be Q * R. So when transforming a
* vector v with the new quaternion by using Q * R * v, the
* rotation added by this method will be applied first!
*
* @see #rotateAxis(float, float, float, float, Quaternionf)
*
* @param angle
* the angle in radians to rotate about the specified axis
* @param axis
* the rotation axis
* @param dest
* will hold the result
* @return dest
*/
Quaternionf rotateAxis(float angle, Vector3fc axis, Quaternionf dest);
/**
* Compute the difference between this and the other quaternion
* and store the result in dest.
*
* The difference is the rotation that has to be applied to get from
* this rotation to other. If T is this, Q
* is other and D is the computed difference, then the following equation holds:
*
* T * D = Q
*
* It is defined as: D = T^-1 * Q, where T^-1 denotes the {@link #invert(Quaternionf) inverse} of T.
*
* @param other
* the other quaternion
* @param dest
* will hold the result
* @return dest
*/
Quaternionf difference(Quaternionfc other, Quaternionf dest);
/**
* Obtain the direction of +X before the rotation transformation represented by this quaternion is applied.
*
* This method is equivalent to the following code:
*
* Quaternionf inv = new Quaternionf(this).invert();
* inv.transform(dir.set(1, 0, 0));
*
*
* @param dir
* will hold the direction of +X
* @return dir
*/
Vector3f positiveX(Vector3f dir);
/**
* Obtain the direction of +X before the rotation transformation represented by this normalized quaternion is applied.
* The quaternion must be {@link #normalize(Quaternionf) normalized} for this method to work.
*
* This method is equivalent to the following code:
*
* Quaternionf inv = new Quaternionf(this).conjugate();
* inv.transform(dir.set(1, 0, 0));
*
*
* @param dir
* will hold the direction of +X
* @return dir
*/
Vector3f normalizedPositiveX(Vector3f dir);
/**
* Obtain the direction of +Y before the rotation transformation represented by this quaternion is applied.
*
* This method is equivalent to the following code:
*
* Quaternionf inv = new Quaternionf(this).invert();
* inv.transform(dir.set(0, 1, 0));
*
*
* @param dir
* will hold the direction of +Y
* @return dir
*/
Vector3f positiveY(Vector3f dir);
/**
* Obtain the direction of +Y before the rotation transformation represented by this normalized quaternion is applied.
* The quaternion must be {@link #normalize(Quaternionf) normalized} for this method to work.
*
* This method is equivalent to the following code:
*
* Quaternionf inv = new Quaternionf(this).conjugate();
* inv.transform(dir.set(0, 1, 0));
*
*
* @param dir
* will hold the direction of +Y
* @return dir
*/
Vector3f normalizedPositiveY(Vector3f dir);
/**
* Obtain the direction of +Z before the rotation transformation represented by this quaternion is applied.
*
* This method is equivalent to the following code:
*
* Quaternionf inv = new Quaternionf(this).invert();
* inv.transform(dir.set(0, 0, 1));
*
*
* @param dir
* will hold the direction of +Z
* @return dir
*/
Vector3f positiveZ(Vector3f dir);
/**
* Obtain the direction of +Z before the rotation transformation represented by this normalized quaternion is applied.
* The quaternion must be {@link #normalize(Quaternionf) normalized} for this method to work.
*
* This method is equivalent to the following code:
*
* Quaternionf inv = new Quaternionf(this).conjugate();
* inv.transform(dir.set(0, 0, 1));
*
*
* @param dir
* will hold the direction of +Z
* @return dir
*/
Vector3f normalizedPositiveZ(Vector3f dir);
/**
* Conjugate this by the given quaternion q by computing q * this * q^-1
* and store the result into dest.
*
* @param q
* the {@link Quaternionfc} to conjugate this by
* @param dest
* will hold the result
* @return dest
*/
Quaternionf conjugateBy(Quaternionfc q, Quaternionf dest);
/**
* Determine whether all components are finite floating-point values, that
* is, they are not {@link Float#isNaN() NaN} and not
* {@link Float#isInfinite() infinity}.
*
* @return {@code true} if all components are finite floating-point values;
* {@code false} otherwise
*/
boolean isFinite();
}