transforms.inc

## 7.19 transforms.inc

Several useful transformation macros. All these macros produce transformations, you can use them anywhere you can use scale, rotate, etc. The descriptions will assume you are working with an object, but the macros will work fine for textures, etc.

`Shear_Trans(A, B, C)`. This macro reorients and deforms an object so its original XYZ axes point along A, B, and C, resulting in a shearing effect when the vectors are not perpendicular. You can also use vectors of different lengths to affect scaling, or use perpendicular vectors to reorient the object.
Parameters:

- `A, B, C` = Vectors representing the new XYZ axes for the transformation.

`Matrix_Trans(A, B, C, D)`. This macro provides a way to specify a matrix transform with 4 vectors. The effects are very similar to that of the Shear_Trans() macro, but the fourth parameter controls translation.
Parameters:

- `A, B, C, D` = Vectors for each row of the resulting matrix.

`Axial_Scale_Trans(Axis, Amt)`. A kind of directional scale, this macro will "stretch" an object along a specified axis.
Parameters:

- `Axis` = A vector indicating the direction to stretch along.
- Amt = The amount to stretch.

`Axis_Rotate_Trans(Axis, Angle)`. This is equivalent to the transformation done by the vaxis_rotate() function, it rotates around an arbitrary axis.
Parameters:

- `Axis` = A vector representing the axis to rotate around.
- `Angle` = The amount to rotate by.

`Rotate_Around_Trans(Rotation, Point)`. Ordinary rotation operates around the origin, this macro rotates around a specific point.
Parameters:

- `Rotation` = The rotation vector, the same as the parameter to the rotate keyword.
- `Point` = The point to rotate around.

`Reorient_Trans(Axis1, Axis2)`. This aligns `Axis1` to `Axis2` by rotating the object around a vector perpendicular to both axis1 and axis2.
Parameters:

- `Axis1` = Vector to be rotated.
- `Axis2` = Vectors to be rotated towards.

`Point_At_Trans(YAxis)`. This macro is similar to Reorient_Trans(), but it points the y axis along Axis.
Parameters:

- `YAxis` = The direction to point the y axis in.

`Center_Trans(Object, Axis)`. Calculates a transformation which will center an object along a specified axis. You indicate the axes you want to center along by adding "x", "y", and "z" together in the Axis parameter.

Note: this macro actually computes the transform to center the bounding box of the object, which may not be entirely accurate. There is no way to define the "center" of an arbitrary object.

Parameters:

- `Object` = The object the center transform is being computed for.
- `Axis` = The axes to center the object on.

Usage:

    object {MyObj Center_Trans(MyObj, x)} //center along x axis

You can also center along multiple axes:

    object {MyObj Center_Trans(MyObj, x+y)} //center along x and y axis

`Align_Trans(Object, Axis, Pt)`. Calculates a transformation which will align the sides of the bounding box of an object to a point. Negative values on Axis will align to the sides facing the negative ends of the coordinate system, positive values will align to the opposite sides, 0 means not to do any alignment on that axis.
Parameters:

- `Object` = The object being aligned.
- `Axis` = A combination of +x, +y, +z, -x, -y, and -z, or a vector where each component is -1, 0, or +1 specifying the faces of the bounding box to align to the point.
- `Point` = The point to which to align the bounding box of the object.

Usage:

      object {
         MyObj
         Align_Trans(MyObj, x, Pt) //Align right side of object to be
                                   //coplanar with Pt
         Align_Trans(MyObj,-y, Pt) //Align bottom of object to be
                                   // coplanar with Pt
      }

`vtransform(Vect, Trans)` and `vinv_transform(Vect, Trans)`.
The `vtransform()` macro takes a transformation (rotate, scale, tranlate, etc...) and a point, and returns the result of applying the transformation to the point. The `vinv_transform()` macro is similar, but applies the inverse of the transform, in effect "undoing" the transformation. You can combine transformations by enclosing them in a transform block.
Parameters:

- `Vect` = The vector to which to apply the transformation.
- `Trans` = The transformation to apply to Vect.

`Spline_Trans(Spline, Time, SkyVector, ForeSight, Banking)`. This macro aligns an object to a spline for a given time value. The Z axis of the object will point in the forward direction of the spline and the Y axis of the object will point upwards.
Parameters:

- `Spline` = The spline that the object is aligned to.
- `Time` = The time value to feed to the spline, for example clock.
- `Sky` = The vector that is upwards in your scene, usually y.
- `Foresight` = A positive value that controls how much in advance the object will turn and bank. Values close to 0 will give precise results, while higher values give smoother results. It will not affect parsing speed, so just find the value that looks best.
- `Banking` = How much the object tilts when turning. The amount of tilting is equally much controlled by the ForeSight value.

Usage:

       object {MyObj Spline_Trans(MySpline, clock, y, 0.1, 0.5)}