Difference between revisions of "Vector"
m (→Movement) 
TomEdwards (talk  contribs) (→Orientation: simplified) 

Line 15:  Line 15:  
* <code>vec</code> (or sometimes just <code>v</code>) identifies the variable as a <code>Vector</code>.  * <code>vec</code> (or sometimes just <code>v</code>) identifies the variable as a <code>Vector</code>.  
−  +  == Orientation ==  
−  
−  +  A vector does not have an orientation; that is determined by the code that uses it.  
−  +  In the vast majority of cases a vector will be interpreted as '''world axis aligned''' regardless of an entity's rotation, but there are few cases(e.g. applying physics forces), where they are instead '''object axis aligned'''.  
−  +  There is no way of telling which interpretation will be used from the variable, so check for function comments when in doubt. Use <code>VectorRotate()</code> and <code>VectorIRotate()</code> to translate between alignments.  
−  
−  
−  
−  
−  
−  
−  <  
== Uses ==  == Uses == 
Revision as of 15:50, 15 April 2009
Vector is a C++ class that represents a line with direction and length, starting at the current origin.
Each vector contains three vec_t
'ordinates'. (0,20,5)
means 20 units in front of and 5 units above the current origin.
CUtlVector
in Source.Declaration
Vector vecMyVector = Vector(0,20,5);
 The classname
Vector
is casesensitive.  You could also assign to the X, Y and Z member variables separately.

vec
(or sometimes justv
) identifies the variable as aVector
.
Orientation
A vector does not have an orientation; that is determined by the code that uses it.
In the vast majority of cases a vector will be interpreted as world axis aligned regardless of an entity's rotation, but there are few cases(e.g. applying physics forces), where they are instead object axis aligned.
There is no way of telling which interpretation will be used from the variable, so check for function comments when in doubt. Use VectorRotate()
and VectorIRotate()
to translate between alignments.
Uses
Positioning
Every entity's position is stored as a vector relative to its parent. You are likely to be familiar with this idea already as Cartesian grid coordinates.
The parentrelative vector stored by the entity is 'local'; calculating an 'absolute' vector relative to the world requires extra work. The two Abs functions below do that work for you, but are more expensive.
Movement
An entity attempts to move the length of its velocity vector once per second. The code looks something like this:
Vector velocity = Vector(0,5,0); // 5 units/second in the +Y direction Vector vecNewOrigin = GetAbsOrigin() + velocity * gpGlobals>frametime; // frametime is in seconds, e.g. 0.033 SetAbsOrigin(vecNewOrigin);
Notice how frametime
is used to regulate the entity's speed regardless of how long each frame takes to calculate. See scalar multiplication for more detail on the operation.
As with the origin, velocity is stored relative to the parent. AbsVelocity represents the velocity relative to the rest frame of the world, and is the more commonly used method.
Tracelines
Main article: TraceLines
Tracing is the process of going from a point A towards another point B, and finding out the first thing that we "hit" on our way from A to B (TraceLine).
Operations
All vectors in an operation must have the same origin for the result to make sense. Whether a local or absolute origin is used depends on what you're trying to achieve.
Addition
Adding two (or more) vectors combines them. You have already experienced vector addition if you've ever pushed an object with two hands!
Subtraction
Subtracting one vector from another produces the difference between the two  in other words, how to get to the first location from the second. The result is local to the second vector.
Multiplication
Scalar
Multiplying or dividing a vector by a scalar (i.e. an int or float) will change its length (sometimes called "magnitude") without affecting its direction.
VectorNormalize()
to do this quickly.Dot product
Multiplying two vectors then adding the result's ordinates produces a dot product, which when both vectors have been normalised (see above) is equal to the cosine of the angle between the two vectors.
One use of a dot product is to tell how closely the two vectors align. +1 means a match, 0 means they are perpendicular to each other, and 1 means they are opposed.
This code calculates a dot product with the aid of Source's various helper functions:
Vector vecTarget = GetAbsOrigin()  pTarget>GetAbsOrigin(); // Get local vector to target VectorNormalize(vecTarget); // Normalisation needs to be done beforehand Vector vecFacing; AngleVectors(GetLocalAngles(),&vecFacing); // Convert facing angle to equivalent vector (arrives normalised) float result = DotProduct(vecTarget,vecFacing); // Get the dot product. if (result > 0) Msg("pTarget is in front of me!\n");
Cross product
A cross product is a vector perpendicular to two input vectors. It's used to extrapolate a third dimension from just two: the cross product of a vector pointing down the Xaxis and a vector pointing down the Yaxis is a vector pointing down the Zaxis.
The equation is fiddly and doesn't have to be learnt; just use CrossProduct(vecA,vecB,&vecResult)
. There generally isn't any need to normalise the input vectors. Most modders will likely only use cross products rarely, if ever  but if required, be aware that a moderate amount of math is required to properly understand this operation.
Member functions
Length

vec_t Length()

vec_t LengthSqr()

Length()
returns the vector's length in units. It's faster to useLengthSqr()
and square the value for comparison, however. 
bool IsLengthGreaterThan(flValue)

bool IsLengthLessThan(flValue)
 Helpers that perform fast length checks using
LengthSqr()
. 
void Zero()
 Guess what?
Direction

void Init(vec_t X, Y, Z)
 Quickly set an existing vector's ordinates.

void Random(vec_t minVal,vec_t maxVal)
 Randomises all three ordinates within the given range.

void Negate()
 Reverses the vector's direction without affecting its length.

Vector Max(vOther)

Vector Min(vOther)
 Clamps the vector's ordinates either above or below the given values. The ordinates won't stay in proportion (i.e. direction might change).
Comparison

vec_t DistTo(vOther)

vec_t DistToSqr(vOther)
 Returns the distance between the current vector and
vOther
as a scalar. As ever, the squared flavour is faster. 
vec_t Dot(vOther)
 Returns the dot product of the current vector and
vOther
. 
Vector Cross(vOther)
 Returns the cross product of the current vector and
vOther
. 
bool WithinAABox(vecBoxmin,vecBoxmax)
 Does the vector end within this box? Argument vectors are local.
Casts

Vector2D AsVector2D()
 Casts to Vector2D.

vec_t Length2D()

vec_t Length2DSqr()
 As their standard equivalents, but ignoring the Zaxis.

Base()
 Casts to vec_t. To do: What does that achieve?
Helper functions

vec_t DotProduct(vecA,vecB)
 See #Dot product.

void CrossProduct(const Vector& a, const Vector& b, Vector& result )
 See #Cross product.