How do I use D3DXVec3Normalize()?

Question

It accepts two parameters, the first is an out parameter - a pointer type, so a referenced variable or a pointer to a variable - the second parameter is an in parameter of the same type but const.

This is strange to me, normalizing is a simple calculation, I would expect the function to have one parameter - the vector to be normalised. Why does it have two? could somebody write an example of how I would use it?

Answer 1

Basically it allows you to have an input vector different from an output vector, like so:

D3DXVECTOR3 bulletMovement = /*...*/; // the whole bullet movement
D3DXVECTOR3 bulletDirection = /*...*/; // the DIRECTION of the bullet movement, with a length of 1.
D3DXVec3Normalize(&bulletDirection , &bulletMovement);

This way you keep your whole bullet movement intact and simply modify the direction, because that's the only vector that you want with a length of 1.

It may not be always useful, but if gives you more control over the normalization (although you could do without it being so flexible by making a copy and normalizing it after).

What you generally want is this:

D3DXVECTOR3 mouseDirection = /*...*/;
D3DXVec3Normalize(&mouseDirection, &mouseDirection);

But keep in mind that you have the possibility to have different input/output parameters.

Answer 2

normalizing is a simple calculation, I would expect the function to have one parameter - the vector to be normalised. Why does it have two? could somebody write an example of how I would use it?

Normalizing is, indeed, relatively simple. It's also an operation that is performed often and consequently should be very fast. Performance considerations are especially important when designing math library middleware like D3DX.

The reason there are two parameters is for efficiency, and to some extent robustness. By providing by-reference (via pointer) output and input parameters, the D3DX normalize function can normalize a vector in place or to a new vector without unnecessary by-value copying of the vector object.

By way of contrast, consider the alternatives: If the normalization function took only a single input vector, it would have only two reasonable options to get the result back to the caller:

1. Return it directly.
2. Modify the input value.

Option (1) would perforce require a copy of the vector to be returned on the stack (a vector which is much larger than the size of a pointer in real-world scenarios) and so would be somewhat less efficient, even if it is a slightly more natural or convenient API.

Option (2) is cumbersome, would prevent const variables from being normalized without first making a copy, and similarly would require the caller to create a copy if they did not what the input vector modifier. So it's both less convenient and in some cases also less efficient.