External/cglm
1
0
Fork 0
mirror of https://github.com/recp/cglm.git synced 2025-10-04 09:08:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add new alignment option to docs

Browse Source
This commit is contained in:
Recep Aslantas
2018-05-09 16:35:15 +03:00
parent f774925e8a
commit 94b286f1f9
5 changed files with 50 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/source/getting_started.rst
View File

@@ -27,6 +27,13 @@ Alignment is Required:
**vec4** and **mat4** requires 16 byte alignment because vec4 and mat4 operations are
vectorized by SIMD instructions (SSE/AVX).
**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 only is 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.

1
docs/source/index.rst
View File

@@ -40,6 +40,7 @@ Also currently only **float** type is supported for most operations.
getting_started
opengl
api
opt
troubleshooting
Indices and tables

36
docs/source/opt.rst Normal file
View File

@@ -0,0 +1,36 @@
.. default-domain:: C
Options
===============================================================================
A few options are provided via macros.
Alignment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As default, cglm requires types to be aligned. Alignment requirements:
vec3: 8 byte
vec4: 16 byte
mat4: 16 byte
versor: 16 byte
By starting **v0.4.5** cglm provides an option to disable alignment requirement.
To enable this option define **CGLM_ALL_UNALIGNED** macro before all headers.
You can define it in Xcode, Visual Studio (or other IDEs) or you can also prefer
to define it in build system. If you use pre-compiled verisons then you
have to compile cglm with **CGLM_ALL_UNALIGNED** macro.
**VERY VERY IMPORTANT:** If you use cglm in multiple projects and
those projects are depends on each other, then
| *ALWAYS* or *NEVER USE* **CGLM_ALL_UNALIGNED** macro in linked projects
if you do not know what you are doing. Because a cglm header included
via 'project A' may force types to be aligned and another cglm header
included via 'project B' may not require alignment. In this case
cglm functions will read from and write to **INVALID MEMORY LOCATIONs**.
ALWAYS USE SAME CONFIGURATION / OPTION for **cglm** if you have multiple projects.
For instance if you set CGLM_ALL_UNALIGNED in a project then set it in other projects too

3
docs/source/troubleshooting.rst
View File

@@ -43,6 +43,9 @@ you may do it yourself.
**This MSVC issue is still in TODOs.**
**UPDATE:** By starting v0.4.5 cglm provides an option to disable alignment requirement.
Also alignment is disabled for older msvc verisons as default. Now alignment only is required in Visual Studio 2017 version 15.6+ if CGLM_ALL_UNALIGNED macro is defined.
Crashes, Invalid Memory Access:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

6
include/cglm/types.h
View File

@@ -9,10 +9,10 @@
#define cglm_types_h
#if defined(_MSC_VER)
#if _MSC_VER < 1913 /* Visual Studio 2017 version 15.6 */
# define CGLM_ALL_UNALIGNED
/* do not use alignment for older visual studio versions */
# define CGLM_ALIGN(X) /* __declspec(align(X)) */
#if _MSC_VER < 1913 /* Visual Studio 2017 version 15.6 */
# define CGLM_ALL_UNALIGNED
# define CGLM_ALIGN(X) /* no alignment */
#else
# define CGLM_ALIGN(X) __declspec(align(X))
#endif