Plastic Gem #21: Vector Functions and Aligning Objects

Download Code File




Plastic Gem # 21 : Vector Functions

Difficulty: Easy

Hi Paul Dana here from Plastic Games. This is another short but loveable gem. I will show you some vector functions I exposed to the script that have proven very useful.

1) Unzipping the files

Unzip the pg21_vectorFunctions.zip. In there you will find a script file called addToMathTypes.cc.

2) Executing the script

For this gem we don't really need a new file. The functions I have provided can just be added to the end of an existing file. File the file mathTypes.cc in your engine/math folder. If you are using TGEA this file is called MathTypes.cpp. Edit that file and add the code from addToMathTypes.cc to the end of the file and recompile.

3) The new functions

VectorGetRotationFromZ(VectorF vec) - get AxisAng from up vector.
VectorGetRotationFromX(VectorF vec) - get AxisAng from right vector.
VectorGetAnglesFromVector(VectorF vec) - get AxisAng from forward vector.
VectorGetVectorFromAngles(AxisAng rot) - get forward vector from angle

I apologize that the first two methods are named so different from the third, given that they are congruent. The third one is a method that already exists in the C++ code (MathUtils::getAnglesFromVector) and so it got that name. The first two are the exact equivalent methods (i.e. they compute an axis-angle rotation you can use to orient an object in the world) but operate on the Z and X axis instead of the Y axis. The fourth method is sort of the opposite of the third method. Given an axis-angle rotation it gives you the forward vector that corresponds to.

4) Using the functions

I mainly use these methods to automatically orient shapes in the world. For example let's say some shape, like a fence rail, has been modeled to start at the 0,0,0 point and is aligned with the positive X axis. Let's also say we know that this fence rail is 4 units long. Given these facts we could use the VectorGetRotationFromX() method to automatically align the fence rail between two known points - say locations of fence posts we have placed. That code would look like this:

// %post and %nextPost are the post objects...

   // rail is 4 units long...
   %railLength = 4.0;

   // get vector from post to next post
   %vec = VectorSub(%nextPost.getPosition(), %post.getPosition());
   
   // get that distance
   %newDist = VectorLen(%vec);
   
   // get normalized vec
   %unitVec = VectorNormalize(%vec);

   // get scale rotation and position...
   %scale = %newDist / %railLength;
   %rot = VectorGetRotationFromX(%unitVec); // a C++ gem
   %pos = %post.getPosition();

   // create and scale a rail...
   %rail = new StaticShape()
   {
      dataBlock = SomeRailStaticShapeDatablock;
      position = %pos;
      scale = %scale SPC "1 1";
      rotation = %rot;
   };
   if (isObject(MissionGroup))
      MissionGroup.add(%rail);

If the shape was instead modelled along the positive Z axis we could do the same thing but would use the VectorGetRotationFromZ() method. If it was aligned along Y we would use the VectorGetAnglesFromVector() method.

5) Why not use your fancy dynamic creation method from the previous gem?

Excellent question. I wish you had not brought that up. The answer is that I haven't gotten that to work. Theoretically (assuming you had followed Gem #20 to get the dynamic creation method) you could calculate the position and rotation as above, but then handle the creation and scaling this way:

%rail = SomeRailStaticShapeDatablock.createStaticShape();
%rail.setScale( %scale SPC "1 1");
%rail.setTransform(%pos SPC %rot);

Someone else can feel free to experiment with this and try to discover why I could not get the above method to work.

The Next Gem

That's all for this gem. I have no idea what I am doing for the next gem. Your guess is as good as mine!