106 lines
4.3 KiB
ReStructuredText
106 lines
4.3 KiB
ReStructuredText
|
Getting Started
|
|||
|
|
================================
|
|||
|
|
|
|||
|
|
Types:
|
|||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|||
|
|
|
|||
|
|
**cglm** uses **glm** prefix for all functions e.g. glm_lookat. You can see supported types in common header file:
|
|||
|
|
|
|||
|
|
.. code-block:: c
|
|||
|
|
:linenos:
|
|||
|
|
|
|||
|
|
typedef float vec2[2];
|
|||
|
|
typedef float vec3[3];
|
|||
|
|
typedef int ivec3[3];
|
|||
|
|
typedef CGLM_ALIGN_IF(16) float vec4[4];
|
|||
|
|
typedef vec4 versor;
|
|||
|
|
typedef vec3 mat3[3];
|
|||
|
|
|
|||
|
|
#ifdef __AVX__
|
|||
|
|
typedef CGLM_ALIGN_IF(32) vec4 mat4[4];
|
|||
|
|
#else
|
|||
|
|
typedef CGLM_ALIGN_IF(16) vec4 mat4[4];
|
|||
|
|
#endif
|
|||
|
|
|
|||
|
|
As you can see types don't store extra informations in favor of space.
|
|||
|
|
You can send these values e.g. matrix to OpenGL directly without casting or calling a function like *value_ptr*
|
|||
|
|
|
|||
|
|
Alignment Is Required:
|
|||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|||
|
|
|
|||
|
|
**vec4** and **mat4** requires 16 (32 for **mat4** if AVX is enabled) byte alignment because **vec4** and **mat4** operations are vectorized by SIMD instructions (SSE/AVX/NEON).
|
|||
|
|
|
|||
|
|
**UPDATE:**
|
|||
|
|
By starting v0.4.5 cglm provides an option to disable alignment requirement, it is enabled as default
|
|||
|
|
|
|||
|
|
| Check :doc:`opt` page for more details
|
|||
|
|
|
|||
|
|
Also alignment is disabled for older msvc verisons as default. Now alignment is only required in Visual Studio 2017 version 15.6+ if CGLM_ALL_UNALIGNED macro is not defined.
|
|||
|
|
|
|||
|
|
Allocations:
|
|||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|||
|
|
*cglm* doesn't alloc any memory on heap. So it doesn't provide any allocator.
|
|||
|
|
You must allocate memory yourself. You should alloc memory for out parameters too if you pass pointer of memory location. When allocating memory, don't forget that **vec4** and **mat4** require alignment.
|
|||
|
|
|
|||
|
|
**NOTE:** Unaligned **vec4** and unaligned **mat4** operations will be supported in the future. Check todo list.
|
|||
|
|
Because you may want to multiply a CGLM matrix with external matrix.
|
|||
|
|
There is no guarantee that non-CGLM matrix is aligned. Unaligned types will have *u* prefix e.g. **umat4**
|
|||
|
|
|
|||
|
|
Array vs Struct:
|
|||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|||
|
|
*cglm* uses arrays for vector and matrix types. So you can't access individual
|
|||
|
|
elements like vec.x, vec.y, vec.z... You must use subscript to access vector elements
|
|||
|
|
e.g. vec[0], vec[1], vec[2].
|
|||
|
|
|
|||
|
|
Also I think it is more meaningful to access matrix elements with subscript
|
|||
|
|
e.g **matrix[2][3]** instead of **matrix._23**. Since matrix is array of vectors,
|
|||
|
|
vectors are also defined as array. This makes types homogeneous.
|
|||
|
|
|
|||
|
|
**Return arrays?**
|
|||
|
|
|
|||
|
|
Since C doesn't support return arrays, cglm also doesn't support this feature.
|
|||
|
|
|
|||
|
|
Function design:
|
|||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|||
|
|
|
|||
|
|
.. image:: cglm-intro.png
|
|||
|
|
:width: 492px
|
|||
|
|
:height: 297px
|
|||
|
|
:align: center
|
|||
|
|
|
|||
|
|
cglm provides a few way to call a function to do same operation.
|
|||
|
|
|
|||
|
|
* Inline - *glm_, glm_u*
|
|||
|
|
* Pre-compiled - *glmc_, glmc_u*
|
|||
|
|
|
|||
|
|
For instance **glm_mat4_mul** is inline (all *glm_* functions are inline), to make it non-inline (pre-compiled),
|
|||
|
|
call it as **glmc_mat4_mul** from library, to use unaligned version use **glm_umat4_mul** (todo).
|
|||
|
|
|
|||
|
|
Most functions have **dest** parameter for output. For instance mat4_mul func looks like this:
|
|||
|
|
|
|||
|
|
.. code-block:: c
|
|||
|
|
|
|||
|
|
CGLM_INLINE
|
|||
|
|
void
|
|||
|
|
glm_mat4_mul(mat4 m1, mat4 m2, mat4 dest)
|
|||
|
|
|
|||
|
|
The dest parameter is out parameter. Result will be stored in **dest**.
|
|||
|
|
Also in this case matrix multiplication order is dest = m1 * m2.
|
|||
|
|
|
|||
|
|
* Changing parameter order will change the multiplication order.
|
|||
|
|
* You can pass all parameter same (this is similar to m1 `*=` m1), you can pass **dest** as m1 or m2 (this is similar to m1 `*=` m2)
|
|||
|
|
|
|||
|
|
**v** postfix in function names
|
|||
|
|
-------------------------------
|
|||
|
|
|
|||
|
|
You may see **v** postfix in some function names, v stands for vector.
|
|||
|
|
For instance consider a function that accepts three parameters x, y, z.
|
|||
|
|
This function may be overloaded by **v** postfix to accept vector (vec3) instead of separate parameters.
|
|||
|
|
In some places the v means that it will be apply to a vector.
|
|||
|
|
|
|||
|
|
**_to** postfix in function names
|
|||
|
|
---------------------------------
|
|||
|
|
|
|||
|
|
*_to* version of function will store the result in specified parameter instead of in-out parameter.
|
|||
|
|
Some functions don't have _to prefix but they still behave like this e.g. glm_mat4_mul.
|