View source for User:TomEdwards/Vector draft

{{toc-right}}

'''Vector''' is a C++ class that represents a line with direction and length, starting at the current [[origin]].

Each vector contains three <code>[[vec_t]]</code> 'ordinates'. <code>(0,20,5)</code> is a Vector that ends 20 [[unit]]s in front and 5 units above the current origin.

{{note|Source's vector class is ''very'' different to [[Wikipedia:Vector (C++)|the Standard Template Library's]], which is a type of [[Wikipedia:Array|array]]. The STL-style vector has been renamed <code>[[CUtlVector]]</code> in Source.}}

== Declaration ==

 Vector vecMyVector = Vector(0,20,5);

You could also assign to the X, Y and Z member variables separately.

== 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 [[coordinates|grid coordinates]].

The parent-relative 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]].

* <code>[[GetAbsOrigin()]]</code>, <code>[[SetAbsOrigin()]]</code>
* <code>[[GetLocalOrigin()]]</code>, <code>[[SetLocalOrigin()]]</code>

=== 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 forward''
 
 Vector vecNewOrigin = GetAbsOrigin() + velocity * [[gpGlobals]]->frametime; ''// frametime is in seconds, e.g. 0.033''
 
 SetAbsOrigin(vecNewOrigin);

Notice how <code>frametime</code> is used to regulate the entity's speed regardless of how long each frame takes to calculate. See [[#Scalar|scalar multiplication]] for more detail on the operation.

As with the origin, velocity is stored relative to the entity. {{todo|What does AbsVelocity mean?}}

* <code>[[GetAbsVelocity()]]</code>, <code>[[SetAbsVelocity()]]</code>
* <code>[[GetLocalVelocity()]]</code>, <code>[[SetLocalVelocity()]]</code>

=== Tracelines ===

{{todo|Tracelines are glorified vectors, right?}}

== 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!

[[Image:Vector_add.png|center|Vector addition: (4,1) + (-3,1) = (1,2)]]

=== 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.

[[Image:Vector_subtraction.png|center|Vector subtraction: (2,3) - (-2,1) = (4,2)]]

{{tip|The order in which you subtract defines the direction of the vector.}}

=== Multiplication ===

==== Scalar ====

Multiplying or dividing a vector by a [[Wikipedia:Scalar|scalar]] (i.e. an [[int]] or [[float]]) will change its '''length''' (sometimes called "magnitude") without affecting its direction.

[[Image:Vector-scalar_multiply.png|center|Vector-scalar multiplication: (1,2) x 2 = (2,4)]]

{{tip|Dividing a vector by its length [[normal]]ises it. Use <code>VectorNormalize()</code> to do this quickly.}}

==== Dot product ====

Multiplying two normalised (see above) vectors then adding the result's ordinates produces a '''dot product''', which tells you how closely the direction of two vectors match. +1 means a match, 0 means they are perpendicular to each other, and -1 means they are opposed.

{{note|''True dot products are only produced when the length of both vectors is 1.'' The [[normal]]isation step has been skipped in the following demonstration to make its equations simpler (but the positive/zero/negative rule still applies).}}

[[Image:Vector_dotproduct.png|center|Vector dot products: (2,2) x (-2,0) = (-4,0) = -4; (2,2) x (-2,2) = (-4,4) = 0; (2,2) x (2,2) = (4,4) = 8]]

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()|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");

{{tip|There is no need to normalise if you only care about whether one location is in front of another.}}

==== Cross product ====

A '''cross product''' is a vector perpendicular to two input vectors. The cross product of a vector pointing down the X-axis and a vector pointing down the Y-axis is a vector pointing down the Z-axis. It's used to extrapolate a third dimension from just two.

The equation is fiddly and doesn't have to be learnt; just use <code>CrossProduct()</code>. There generally isn't any need to normalise the input vectors.

== Member functions ==

; <code>[[float]]/[[vec_t]] Length()</code>
; <code>vec_t VectorLength(const Vector&)</code>
: Returns the vector's length, in units.
; <code>vec_t LengthSqr()</code>
: Returns length squared.
; <code>vec_t Length2D()</code>
; <code>vec_t Length2DSqr()</code>
: {{todo|???}}
; <code>void Negate()</code>
: Reverses the vector's direction without affecting its length.
; <code>vec_t DotProduct(const Vector& a, const Vector& b)</code>
: {{todo|Someting to do with determining how closely two vectors match.}}
; <code>void CrossProduct(const Vector& a, const Vector& b, Vector& result )</code>
: {{todo|Something to do with creating a surface normal.}}
; <code>bool WithinAABox( Vector const &boxmin, Vector const &boxmax)</code>
: Does the Vector intersect this axis-aligned box? {{todo|Are argument vectors local or abs?}}

== Helper functions ==

* <code>[[UTIL_VecToYaw()]]</code>, <code>[[UTIL_VecToPitch()]]</code>
* <code>[[AngleVectors()]]</code>
* <code>[[VectorNormalize()]]</code>

== See also ==

* [[Wikipedia:Euclidean vector]]
* <code>[[QAngle]]</code>
* <code>[[vec_t]]</code>
* <code>[[VectorVectors]]</code>
* <code>[[CUtlVector]]</code>

[[Category:Glossary]]
[[Category:Variables]]
[[Category:Helpers]]