geVec3d

Description: 3D Vector interface

Source file: …\genesis3d\OpenSource\Source\Math\VEC3D.h

Contents:

Functions: Add, AddScaled, Clear, Compare, Copy, CrossProduct, DistanceBetween, DotProduct, Get, GetElement, Inverse , IsValid, Length, LengthSquared, MA, Normalize, Scale, Set, Subtract

Types: geVec3d

Additions for Genesis3D v1.6: None

Proposed function: geVec3d_Reflect

Notes: view [Contents: Reflection, Dot Product Mathematical properties]

 

Types:

geVec3d

typedef struct {
   geFloat X, Y, Z;
} geVec3d;

Return to Contents

Functions:

GENESISAPI void GENESISCC  geVec3d_Add(const geVec3d* V1, const geVec3d* V2,  geVec3d* VSum);

This function adds V1 to V2 returning the result in VSum.

Returns: nothing.

Return to Contents

GENESISAPI void GENESISCC  geVec3d_AddScaled(const geVec3d* V1, const geVec3d* V2, geFloat Scale, geVec3d* V1PlusV2Scaled);

This function calculates V1 + V2*Scale returning the result in V1PlusV2Scaled.

Returns: nothing.

Return to Contents

GENESISAPI void GENESISCC  geVec3d_Clear(geVec3d* V);

This function clears all the elements of V to 0.0f.

Returns: nothing.

Return to Contents

GENESISAPI geBoolean GENESISCC geVec3d_Compare(const geVec3d* V1, const geVec3d* V2, geFloat tolerance);

This function compares V1 to V2, if the difference between any of the elements is more than tolerance, then it returns GE_FALSE, otherwise GE_TRUE.

Returns: the result.

Note:
Result of GE_TRUE --> No Difference
Result of GE_FALSE --> Difference > tolerance

Return to Contents

GENESISAPI void GENESISCC  geVec3d_Copy(const geVec3d* Vsrc, geVec3d* Vdst);

This function copies Vsrc to Vdst.

Returns: nothing.

Return to Contents

GENESISAPI void GENESISCC  geVec3d_CrossProduct(const geVec3d* V1, const geVec3d* V2, geVec3d* VResult);

This function calculates the cross product of the two vectors V1 and V2 returning the result in VResult.  The cross product of two vectors can be thought of as the vector that is perpendicular to each with a length equal to the area of the parallelogram formed by the two vectors.

Returns: nothing.

Properties of a cross product vector:

For the following discussion, consider the equation c = a x b.  The bold variables are vectors, and "x" means cross product, which is sometimes also called a "vector product".   |a| means the modulus, or magnitude (length) of a vector.

A cross product has the following properties:
  1.  |c| = |a| * |b| * sin (a; b)         (The magnitude of the resulting vector equals the magnitude of vector a times the magnitude of vector b times the sine of the angle between these two vectors)
  2.  c is perpendicular to the plane containing vectors a and b.
  3.  a, b, and c for a RIGHT trihedral, that is, the shortest rotation of a towards b is seen, from the end point of c (looking towards the base of c), as a counter-clockwise rotation.

General properties of a cross product:
1.  a x a = 0
2.  a x b = -b x a   (the cross product is anticommutative)
3.  (a+b) x c = a x c + b x c
4.  ka x b = k(a x b)

The coordinates of the cross product with respect to a Cartesian coordinate system is given as follows:
(A X B)x = AyBz - AzBy
(A X B)y = AzBx - AxBz
(A X B)z = AxBy - AyBx

(Notes from: Concise Handbook of Mathematics and Physics. Alenitsyn AG. CRC Press. 1997)

(See also notes below)

Return to Contents

GENESISAPI geFloat GENESISCC  geVec3d_DistanceBetween(const geVec3d* V1, const geVec3d* V2);

This function calculates the distance between the two points represented by V1 and V2.

Returns: the result.

Notes:
    from VEC3D.H: returns length of V1-V2

Return to Contents

GENESISAPI geFloat GENESISCC geVec3d_DotProduct(const geVec3d* V1, const geVec3d* V2);

This function calculates the Dot Product of the two vectors returning the result.

Returns: the result.

Note: the result is not a vector, thus has no orientation (in contrast to a cross product).

Properties of a dot product:

For the following discussion, consider the equation c = a t b.  The bold variables are vectors, and "t" means dot product, also knows as the "scalar or inner product".   |a| means the modulus, or magnitude (length) of a vector.

For a dot product, the following are true:
1.  c = a t b = |a| * |b| * cos (a; b)    (The dot product of two vectors (a and b) is the magnitude of a times the magnitude of b times the cosine of the angle between the two vectors.)
2.  c = A t B = AxBx + AyBy + AzBz

(Notes from: Concise Handbook of Mathematics and Physics. Alenitsyn AG. CRC Press. 1997)

See notes for tutorial on one use of dot product: view

Return to Contents

GENESISAPI void GENESISCC  geVec3d_Get(const geVec3d* V, geFloat* X, geFloat* Y, geFloat* Z);

This function returns the components of the specified vector.

Returns: nothing.

Return to Contents

GENESISAPI geFloat GENESISCC  geVec3d_GetElement(geVec3d* V, int Index);

This function returns the specified (0,1,2) element of the vector V.

Returns: the specified element.

Return to Contents

GENESISAPI void GENESISCC  geVec3d_Inverse(geVec3d* V);

This function calculates the inverse of the given vector, replacing the original values.

Returns: nothing.

Return to Contents

GENESISAPI geBoolean GENESISCC  geVec3d_IsNormalized(const geVec3d* V);

This function checks whether the vector V is normalized.  In other words whether its length is equal to 1.0f (within a certain tolerance).

Returns: GE_TRUE if the vector is normalized, GE_FALSE otherwise.

Return to Contents

GENESISAPI geBoolean GENESISCC geVec3d_IsValid(const geVec3d* V);

This function checks each of the elements of V to assure that they are real.

Returns: GE_TRUE if the vector is valid, GE_FALSE otherwise.

Return to Contents

GENESISAPI geFloat GENESISCC geVec3d_Length(const geVec3d* V1);

This function calculates the length of the given vector.

Returns: the result.

Return to Contents

GENESISAPI geFloat GENESISCC geVec3d_LengthSquared(const geVec3d* V1);

This function calculates the length of the given vector and squares it.  Note that this function should be used whenever the square of the length of a vector is needed as it is actually faster than calculating the length of the vector, much less doing so then squaring it.

Returns: the result.

Return to Contents

GENESISAPI void GENESISCC  geVec3d_MA(geVec3d* V1, geFloat Scale, const geVec3d* V2, geVec3d* V1PlusV2Scaled);

This function produces the same result as  geVec3d_AddScaled.

Returns: nothing

Return to Contents 

GENESISAPI geFloat GENESISCC geVec3d_Normalize(geVec3d* V1);

This function normalizes the vector V1 and returns its original length.  Note that the vector value is changed.

Returns: the original length of the vector.

Return to Contents

GENESISAPI void GENESISCC  geVec3d_Scale(const geVec3d* VSrc, geFloat Scale, geVec3d* VDst);

This function calculates VSrc * Scale and returns the result in VDst.

Returns: nothing.

Return to Contents

GENESISAPI void GENESISCC  geVec3d_Set(geVec3d* V, geFloat X, geFloat Y, geFloat Z);

This function sets the values of the elements of V.

Returns: nothing.

Return to Contents


GENESISAPI void GENESISCC  geVec3d_Subtract(const geVec3d* V1, const geVec3d* V2, geVec3d* V1MinusV2);

This function computes the difference between V1 and V2 returning the resultant vector in V1MinusV2.

Returns: nothing.

Return to Contents

Notes:

Contents: Reflection, Dot Product Mathematical properties

Return to Contents

 

Reflection of a vector:

This is a Proposed Function: 

void geVec3d_Reflect(geVec3d* In, geVec3d* Normal, geVec3d* Out, geFloat Scale)
//Purpose: To reflect an In vector off of a plane (defined by Normal), scaled by Scale
//               (This could be used to bounce a ball off a wall).
//Input:      In: Input vector. Does not need to be normalized
//              Normal: A normalized vector from surface to be reflected from.
//              Out: The resulting vector
//              Scale: A scale factor for resulting output vector.
//                         An example of use would be to set at 0.75, so that reflected velocity loses 25% in reflection.
//Note: The general formula is: Out = In - 2*Normal*(In dot Normal)
{
    geVec3d_AddScaled (In, Normal, -2*geVec3d_DotProduct (In, Normal), Out);
    geVec3d_Scale (Out, Scale, Out);
}

Return to Notes Contents   Return to Main Contents

 

Dot Product Notes:

Practical application #1: Project one vector onto another.

The length of the projection of a vector R onto a vector J is:
    = geVec3d_DotProduct(&R, &J) / geVec3d_Length (&J)

Here's one proof:

The definition for a dot product contains the cosine of the angle between the two vectors.
   i.e.:  J t R = |J| * |R| * cos (angle)
We can consider one of the vectors (J) to be aligned with the X axis.
Then our second vector (R) would then be similar to the ray R in the diagram below.
Angle alpha, in the diagram below, is the angle betwen the vectors.
Note: |J| means the length of vector J

Cosine is defined as X / R.
Furthermore X is the projection of R onto the x axis.
   J t R = |J| * |R| * cos (alpha)     //The definition of a dot product
   cos (alpha) = X / |R|                  //The definition of a cosine
   J t R = |J| * |R| * X / |R|          //Substitution
   J t R = |J| * X                          //Cancelling
   X = (J t R) / |J|                         //Rearrangement

Thus, the length of the projection of R onto J is:
     geVec3d_DotProduct(&R, &J) / geVec3d_Length (&J)

Note: if J happened to be a unit vector (length = 1) then dividing by the Length could be avoided.

 

Practical application #2: Find the angle between two vectors.

The angle between two vectors, R and J is:
    = acos (geVec3d_DotProduct(&R, &J) / (geVec3d_Length (&J) * geVec3d_Length (&R)) )

Here's one proof:

The definition for a dot product contains the cosine of the angle between the two vectors.
   i.e.:  J t R = |J| * |R| * cos (angle)
We can consider one of the vectors (J) to be aligned with the X axis.
Then our second vector (R) would then be similar to the ray R in the diagram below.
Angle alpha, in the diagram below, is the angle betwen the vectors
Note: |J| means the length of vector J

   J t R = |J| * |R| * cos (alpha)        //The definition of a dot product
   cos (alpha) = (J t R) / (|J| * |R|)    //Rearrangement
   alpha = arccos ((J t R) / (|J| * |R|))

Thus, then angle between two vectors, R and J is:
    = acos (geVec3d_DotProduct(&R, &J) / (geVec3d_Length (&J) * geVec3d_Length (&R)) )

Note: for purposes of speed, programmers may find it faster to compare the cosine of alpha to the desired value, rather than to calculate the actual value of alpha first, and then test it against a desired angle. For example, if one wants the angle between the two vectors to be 80 degrees or less, it would be faster to test for if ((J t R) / (|J| * |R|) <= 0.17f). Here the cos(80 degrees) is known to be approx 0.17, so it is faster to test this directly.

The cosine of the angle between two vectors, R and J is:
    = geVec3d_DotProduct(&R, &J) / (geVec3d_Length (&J) * geVec3d_Length (&R))

Return to Notes Contents   Return to Main Contents

 

Mathematical Properties:

Mathematical properties of vectors

Dot product (".") mathematical properties

Cross product ("X") mathematical properties
    (see also notes above)

From Mathematics for 3D Game Programming & Computer Graphics by Eric Lengyel (ISBN 1-58450-037-9)

Return to Notes Contents   Return to Main Contents