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:
- Return it directly.
- 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.