diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index fb1433f9..ea360c71 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -3,30 +3,30 @@ Troubleshooting ================================================================================ -It is possible that sometimes you may get crashes or wrong results. +It is possible that you may sometimes get crashes or wrong results. Follow these topics Memory Allocation: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Again, **cglm** doesn't alloc any memory on heap. -cglm functions works like memcpy; it copies data from src, -makes calculations then copy the result to dest. +Recall that **cglm** does not alloc any memory on the heap. +cglm functions work like memcpy; they copy data from src, +make calculations, then copy the result to dest. You are responsible for allocation of **src** and **dest** parameters. Alignment: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**vec4** and **mat4** types requires 16 byte alignment. -These types are marked with align attribute to let compiler know about this +**vec4** and **mat4** types require 16 byte alignment. +These types are marked with the align attribute to let the compiler know about this requirement. -But since MSVC (Windows) throws the error: +Since MSVC (Windows) throws this error: **"formal parameter with requested alignment of 16 won't be aligned"** -The alignment attribute has been commented for MSVC +The alignment attribute has been commented out for MSVC .. code-block:: c @@ -37,61 +37,61 @@ The alignment attribute has been commented for MSVC #endif. So MSVC may not know about alignment requirements when creating variables. -The interesting thing is that, if I remember correctly Visual Studio 2017 +The interesting thing is that, if I remember correctly, Visual Studio 2017 doesn't throw the above error. So we may uncomment that line for Visual Studio 2017, 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 is only required in Visual Studio 2017 version 15.6+ if CGLM_ALL_UNALIGNED macro is not defined. +**UPDATE:** Starting with v0.4.5, cglm provides an option to disable the alignment requirement. +Also, alignment is disabled for older msvc versions by default. Now alignment is only required in Visual Studio 2017 version 15.6+ if the CGLM_ALL_UNALIGNED macro is not defined. Crashes, Invalid Memory Access: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Probably you are trying to write to invalid memory location. +Most likely, you are trying to write to an invalid memory location. -You may used wrong function for what you want to do. +You may have used a wrong function for what you want to do. -For instance you may called **glm_vec4_** functions for **vec3** data type. -It will try to write 32 byte but since **vec3** is 24 byte it should throw -memory access error or exit the app without saying anything. +For example, you may have called a **glm_vec4_** function for a **vec3** data type. +It will try to write 32 bytes, but since **vec3** is 24 bytes, it should throw +a memory access error or exit the app without saying anything. **UPDATE - IMPORTANT:** | On MSVC or some other compilers, if alignment is enabled (default) then double check alignment requirements if you got a crash. - | If you send GLM_VEC4_ONE or similar macros directly to a function, it may be crashed. - | Because compiler may not apply alignment as defined on **typedef** to that macro while passing it (on stack) to a function. + | If you send GLM_VEC4_ONE or similar macros directly to a function, it may crash. + | Because the compiler may not apply alignment as defined on **typedef** to that macro while passing it (on stack) to a function. Wrong Results: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Again, you may used wrong function. +Again, you may have used a wrong function. -For instance if you use **glm_normalize()** or **glm_vec3_normalize()** for **vec4**, -it will assume that passed param is **vec3** and will normalize it for **vec3**. -Since you need to **vec4** to be normalized in your case, you will get wrong results. +For instance if you use **glm_normalize()** or **glm_vec3_normalize()** for a **vec4**, +it will assume that the passed param is a **vec3**, and will normalize it for **vec3**. +Since you need a **vec4** to be normalized in your case, you will get wrong results. -Accessing vec4 type with vec3 functions is valid, you will not get any error, exception or crash. +Accessing a vec4 type with vec3 functions is valid, you will not get any error, exception or crash. You only get wrong results if you don't know what you are doing! -So be carefull, when your IDE (Xcode, Visual Studio ...) tried to autocomplete function names, READ IT :) +So be careful, when your IDE (Xcode, Visual Studio ...) tries to autocomplete function names, READ IT :) -**Also implementation may be wrong please let us know by creating an issue on Github.** +**Also implementation may be wrong, please let us know by creating an issue on Github.** BAD_ACCESS : Thread 1: EXC_BAD_ACCESS (code=EXC_I386_GPFLT) or Similar Errors/Crashes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is similar issue with alignment. For instance if you compiled **cglm** with +This is a similar issue with alignment. For instance if you compiled **cglm** with AVX (**-mavx**, intentionally or not) and if you use **cglm** in an environment that doesn't support AVX (or if AVX is disabled intentionally) e.g. environment that max support SSE2/3/4, then you probably get **BAD ACCESS** or similar... Because if you compile **cglm** with AVX it aligns **mat4** with 32 byte boundary, -and your project aligns that as 16 byte boundary... +and your project aligns that as a 16 byte boundary... -Check alignment, supported vector extension or simd in **cglm** and linked projects... +Check alignment, supported vector extension, or simd in **cglm** and linked projects... Other Issues? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~