diff options
Diffstat (limited to 'libs/cglm/docs/source/euler.rst')
| -rw-r--r-- | libs/cglm/docs/source/euler.rst | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/libs/cglm/docs/source/euler.rst b/libs/cglm/docs/source/euler.rst new file mode 100644 index 0000000..74ba4c2 --- /dev/null +++ b/libs/cglm/docs/source/euler.rst @@ -0,0 +1,182 @@ +.. default-domain:: C + +euler angles +============ + +Header: cglm/euler.h + +You may wonder what **glm_euler_sq** type ( **_sq** stands for sequence ) and +:c:func:`glm_euler_by_order` do. +I used them to convert euler angles in one coordinate system to another. For +instance if you have **Z_UP** euler angles and if you want to convert it +to **Y_UP** axis then :c:func:`glm_euler_by_order` is your friend. For more +information check :c:func:`glm_euler_order` documentation + +You must pass arrays as array, if you use C compiler then you can use something +like this: + +.. code-block:: c + + float pitch, yaw, roll; + mat4 rot; + + /* pitch = ...; yaw = ...; roll = ... */ + glm_euler((vec3){pitch, yaw, roll}, rot); + +Rotation Conveniention +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Current *cglm*'s euler functions uses these convention: + +* Tait–Bryan angles (x-y-z convention) +* Intrinsic rotations (pitch, yaw and roll). + This is reserve order of extrinsic (elevation, heading and bank) rotation +* Right hand rule (actually all rotations in *cglm* use **RH**) +* All angles used in *cglm* are **RADIANS** not degrees + + +**NOTE**: The default :c:func:`glm_euler` function is the short name of +:c:func:`glm_euler_xyz` this is why you can't see :c:func:`glm_euler_xyz`. +When you see an euler function which doesn't have any X, Y, Z suffix then +assume that uses **_xyz** (or instead it accept order as parameter). + +If rotation doesn't work properly, your options: + +1. If you use (or paste) degrees convert it to radians before calling an euler function + +.. code-block:: c + + float pitch, yaw, roll; + mat4 rot; + + /* pitch = degrees; yaw = degrees; roll = degrees */ + glm_euler((vec3){glm_rad(pitch), glm_rad(yaw), glm_rad(roll)}, rot); + +2. Convention mismatch. You may have extrinsic angles, + if you do (if you must) then consider to use reverse order e.g if you have + **xyz** extrinsic then use **zyx** + +3. *cglm* may implemented it wrong, consider to create an issue to report it + or pull request to fix it + +Table of contents (click to go): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Types: + +1. glm_euler_sq + +Functions: + +1. :c:func:`glm_euler_order` +#. :c:func:`glm_euler_angles` +#. :c:func:`glm_euler` +#. :c:func:`glm_euler_xyz` +#. :c:func:`glm_euler_zyx` +#. :c:func:`glm_euler_zxy` +#. :c:func:`glm_euler_xzy` +#. :c:func:`glm_euler_yzx` +#. :c:func:`glm_euler_yxz` +#. :c:func:`glm_euler_by_order` + +Functions documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +.. c:function:: glm_euler_sq glm_euler_order(int ord[3]) + + | packs euler angles order to glm_euler_sq enum. + + To use :c:func:`glm_euler_by_order` function you need *glm_euler_sq*. You + can get it with this function. + + You can build param like this: + + | X = 0, Y = 1, Z = 2 + + if you have ZYX order then you pass this: [2, 1, 0] = ZYX. + if you have YXZ order then you pass this: [1, 0, 2] = YXZ + + As you can see first item specifies which axis will be first then the + second one specifies which one will be next an so on. + + Parameters: + | *[in]* **ord** euler angles order [Angle1, Angle2, Angle2] + + Returns: + packed euler order + +.. c:function:: void glm_euler_angles(mat4 m, vec3 dest) + + | extract euler angles (in radians) using xyz order + + Parameters: + | *[in]* **m** affine transform + | *[out]* **dest** angles vector [x, y, z] + +.. c:function:: void glm_euler(vec3 angles, mat4 dest) + + | build rotation matrix from euler angles + + this is alias of glm_euler_xyz function + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **dest** rotation matrix + +.. c:function:: void glm_euler_xyz(vec3 angles, mat4 dest) + + | build rotation matrix from euler angles + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **dest** rotation matrix + +.. c:function:: void glm_euler_zyx(vec3 angles, mat4 dest) + + | build rotation matrix from euler angles + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **dest** rotation matrix + +.. c:function:: void glm_euler_zxy(vec3 angles, mat4 dest) + + | build rotation matrix from euler angles + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **dest** rotation matrix + +.. c:function:: void glm_euler_xzy(vec3 angles, mat4 dest) + + | build rotation matrix from euler angles + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **dest** rotation matrix + +.. c:function:: void glm_euler_yzx(vec3 angles, mat4 dest) + + build rotation matrix from euler angles + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **dest** rotation matrix + +.. c:function:: void glm_euler_yxz(vec3 angles, mat4 dest) + + | build rotation matrix from euler angles + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **dest** rotation matrix + +.. c:function:: void glm_euler_by_order(vec3 angles, glm_euler_sq ord, mat4 dest) + + | build rotation matrix from euler angles with given euler order. + + Use :c:func:`glm_euler_order` function to build *ord* parameter + + Parameters: + | *[in]* **angles** angles as vector [Xangle, Yangle, Zangle] + | *[in]* **ord** euler order + | *[in]* **dest** rotation matrix |