3D Affine Transforms — cglm 0.9.6 documentation

# 3D Affine Transforms

Header: cglm/affine.h

Before starting, cglm provides two kind of transform functions; pre and post.

Pre functions (T’ = Tnew * T) are like glm_translate, glm_rotate which means it will translate the vector first and then apply the model transformation. Post functions (T’ = T * Tnew) are like glm_translated, glm_rotated which means it will apply the model transformation first and then translate the vector.

glm_translate, glm_rotate are pre functions and are similar to C++ glm which you are familiar with.

In new versions of cglm we added glm_translated, glm_rotated… which are post functions, they are useful in some cases, e.g. append transform to existing transform (apply/append transform as last transform T’ = T * Tnew).

Post functions are named after pre functions with ed suffix, e.g. glm_translate -> glm_translated. So don’t mix them up.

## Initialize Transform Matrices

Functions with _make prefix expect you don’t have a matrix and they create a matrix for you. You don’t need to pass identity matrix.

But other functions expect you have a matrix and you want to transform them. If you didn’t have any existing matrix you have to initialize matrix to identity before sending to transform functions.

There are also functions to decompose transform matrix. These functions can’t decompose matrix after projected.

## Rotation Center

Rotating functions uses origin as rotation center (pivot/anchor point), since scale factors are stored in rotation matrix, same may also true for scalling. cglm provides some functions for rotating around at given point e.g. glm_rotate_at, glm_quat_rotate_at. Use them or follow next section for algorithm (“Rotate or Scale around specific Point (Pivot Point / Anchor Point)”).

Also cglm provides `glm_spin()` and `glm_spinned()` functions to rotate around itself. No need to give pivot. These functions are useful for rotating around center of object.

## Rotate or Scale around specific Point (Anchor Point)

If you want to rotate model around arbitrary point follow these steps:

1. Move model from pivot point to origin: translate(-pivot.x, -pivot.y, -pivot.z)

2. Apply rotation (or scaling maybe)

3. Move model back from origin to pivot (reverse of step-1): translate(pivot.x, pivot.y, pivot.z)

glm_rotate_at, glm_quat_rotate_at and their helper functions works that way. So if you use them you don’t need to do these steps manually which are done by cglm.

The implementation would be:

    1glm_translate(m, pivot);
    2glm_rotate(m, angle, axis);
    3glm_translate(m, pivotInv); /* pivotInv = -pivot */

or just:

    1glm_rotate_at(m, pivot, angle, axis);

## Transforms Order

It is important to understand this part especially if you call transform functions multiple times

glm_translate, glm_rotate, glm_scale and glm_quat_rotate and their helpers functions works like this (cglm provides reverse order as ed suffix e.g glm_translated, glm_rotated see post transforms):

    1TransformMatrix = TransformMatrix * TranslateMatrix; // glm_translate()
    2TransformMatrix = TransformMatrix * RotateMatrix;   // glm_rotate(), glm_quat_rotate()
    3TransformMatrix = TransformMatrix * ScaleMatrix;    // glm_scale()

As you can see it is multiplied as right matrix. For instance what will happen if you call glm_translate twice?

    1glm_translate(transform, translate1); /* transform = transform * translate1 */
    2glm_translate(transform, translate2); /* transform = transform * translate2 */
    3glm_rotate(transform, angle, axis)    /* transform = transform * rotation   */

Now lets try to understand this:

1. You call translate using translate1 and you expect it will be first transform because you call it first, do you?

Result will be `transform = transform * translate1`

2. Then you call translate using translate2 and you expect it will be second transform?

Result will be `transform = transform * translate2`. Now lets expand transform, it was transform * translate1 before second call.

Now it is `transform = transform * translate1 * translate2`, now do you understand what I say?

3. After last call transform will be:

`transform = transform * translate1 * translate2 * rotation`

The order will be; rotation will be applied first, then translate2 then translate1

It is all about matrix multiplication order. It is similar to MVP matrix: MVP = Projection * View * Model, model will be applied first, then view then projection.

Confused?

In the end the last function call applied first in shaders.

As alternative way, you can create transform matrices individually then combine manually, but don’t forget that glm_translate, glm_rotate, glm_scale… are optimized and should be faster (an smaller assembly output) than manual multiplication

     1mat4 transform1, transform2, transform3, finalTransform;
     2
     3glm_translate_make(transform1, translate1);
     4glm_translate_make(transform2, translate2);
     5glm_rotate_make(transform3, angle, axis);
     6
     7/* first apply transform1, then transform2, thentransform3 */
     8glm_mat4_mulN((mat4 *[]){&transform3, &transform2, &transform1}, 3, finalTransform);
     9
    10/* if you don't want to use mulN, same as above */
    11glm_mat4_mul(transform3, transform2, finalTransform);
    12glm_mat4_mul(finalTransform, transform1, finalTransform);

Now transform1 will be applied first, then transform2 then transform3

## Table of contents (click to go):

Functions:

1. `glm_translate_to()`

2. `glm_translate()`

3. `glm_translate_x()`

4. `glm_translate_y()`

5. `glm_translate_z()`

6. `glm_translate_make()`

7. `glm_scale_to()`

8. `glm_scale_make()`

9. `glm_scale()`

10. `glm_scale_uni()`

11. `glm_rotate_x()`

12. `glm_rotate_y()`

13. `glm_rotate_z()`

14. `glm_rotate_make()`

15. `glm_rotate()`

16. `glm_rotate_at()`

17. `glm_rotate_atm()`

18. `glm_decompose_scalev()`

19. `glm_uniscaled()`

20. `glm_decompose_rs()`

21. `glm_decompose()`

Post functions (NEW):

1. `glm_translated_to()`

2. `glm_translated()`

3. `glm_translated_x()`

4. `glm_translated_y()`

5. `glm_translated_z()`

6. `glm_rotated_x()`

7. `glm_rotated_y()`

8. `glm_rotated_z()`

9. `glm_rotated()`

10. `glm_rotated_at()`

11. `glm_spinned()`

## Functions documentation

Affine categories:

- 3D Affine Transforms (common)
- 3D Affine Transforms (pre)
- 3D Affine Transforms (post)