*Note: Including `glm/glm.hpp` and `glm/ext.hpp` is convenient but pull a lot of code which will significantly increase build time, particularly if these files are included in all source files. We may prefer to use the approaches describe in the two following sections to keep the project build fast.*
*Note: Including `<glm/glm.hpp>` and `<glm/ext.hpp>` is convenient but pull a lot of code which will significantly increase build time, particularly if these files are included in all source files. We may prefer to use the approaches describe in the two following sections to keep the project build fast.*
### <aname="section1_2"></a> 1.2. Using separated headers
@ -310,16 +310,18 @@ The following subsections describe each configurations and defines.
### <aname="section2_6"></a> 2.6. GLM\_FORCE\_CXX**: C++ language detection
GLM will automatically take advantage of compilers’ language extensions when enabled. To increase cross platform compatibility and to avoid compiler extensions, a programmer can define GLM\_FORCE\_CXX98 before
any inclusion of <glm/glm.hpp> to restrict the language feature set C++98:
GLM will automatically take advantage of compilers’ language extensions when enabled. To increase cross platform compatibility and to avoid compiler extensions, a programmer can define `GLM_FORCE_CXX98` before
any inclusion of `<glm/glm.hpp>` to restrict the language feature set C++98:
```cpp
#define GLM_FORCE_CXX98
#include<glm/glm.hpp>
```
For C++11 and C++14, equivalent defines are available:
GLM\_FORCE\_CXX11, GLM\_FORCE\_CXX14.
For C++11, C++14, and C++17 equivalent defines are available:
GLSL supports implicit conversions of vector and matrix types. For example, an ivec4 can be implicitly converted into vec4.
Often, this behaviour is not desirable but following the spirit of the library, this is the default behavior in GLM. However, GLM 0.9.6 introduced the define GLM\_FORCE\_EXPLICIT\_CTOR to require explicit conversion for GLM types.
Often, this behaviour is not desirable but following the spirit of the library, this is the default behavior in GLM. However, GLM 0.9.6 introduced the define `GLM_FORCE_EXPLICIT_CTOR` to require explicit conversion for GLM types.
```cpp
#include<glm/glm.hpp>
@ -351,7 +352,7 @@ void foo()
}
```
With GLM\_FORCE\_EXPLICIT\_CTOR define, implicit conversions are not allowed:
With `GLM_FORCE_EXPLICIT_CTOR` define, implicit conversions are not allowed:
```cpp
#define GLM_FORCE_EXPLICIT_CTOR
@ -369,7 +370,7 @@ void foo()
### <aname="section2_8"></a> 2.8. GLM\_FORCE\_INLINE: Force inline
To push further the software performance, a programmer can define GLM\_FORCE\_INLINE before any inclusion of <glm/glm.hpp> to force the compiler to inline GLM code.
To push further the software performance, a programmer can define GLM\_FORCE\_INLINE before any inclusion of `<glm/glm.hpp>` to force the compiler to inline GLM code.
```cpp
#define GLM_FORCE_INLINE
@ -387,9 +388,9 @@ These optimizations will be automatically thanks to compiler arguments.
For example, if a program is compiled with Visual Studio using /arch:AVX, GLM will detect this argument and generate code using AVX instructions automatically when available.
It’s possible to avoid the instruction set detection by forcing the use of a specific instruction set with one of the fallowing define:
GLM\_FORCE\_SSE2, GLM\_FORCE\_SSE3, GLM\_FORCE\_SSSE3, GLM\_FORCE\_SSE41, GLM\_FORCE\_SSE42, GLM\_FORCE\_AVX, GLM\_FORCE\_AVX2 or GLM\_FORCE\_AVX512.
`GLM_FORCE_SSE2`, `GLM_FORCE_SSE3`, `GLM_FORCE_SSSE3`, `GLM_FORCE_SSE41`, `GLM_FORCE_SSE42`, `GLM_FORCE_AVX`, `GLM_FORCE_AVX2` or `GLM_FORCE_AVX512`.
The use of intrinsic functions by GLM implementation can be avoided using the define GLM\_FORCE\_PURE before any inclusion of GLM headers.
The use of intrinsic functions by GLM implementation can be avoided using the define `GLM_FORCE_PURE` before any inclusion of GLM headers.
```cpp
#define GLM_FORCE_PURE
@ -407,7 +408,7 @@ The use of intrinsic functions by GLM implementation can be avoided using the de
Additionally, GLM provides a low level SIMD API in glm/simd directory for users who are really interested in writing fast algorithms.
* GLM\_FORCE\_PRECISION\_MEDIUMP\_UINT: Medium precision
* GLM\_FORCE\_PRECISION\_HIGHP\_UINT: High precision (default)
### <aname="section2_12"></a> 2.12. GLM\_FORCE\_SINGLE\_ONLY: Removed explicit 64-bits floating point types
Some platforms (Dreamcast) doesn't support double precision floating point values. To compile on such platforms, GCC has the --m4-single-only build argument. When defining GLM\_FORCE\_SINGLE\_ONLY before including GLM headers, GLM releases the requirement of double precision floating point values support. Effectivement, all the float64 types are no longer defined and double behaves like float.
Some platforms (Dreamcast) doesn't support double precision floating point values. To compile on such platforms, GCC has the `--m4-single-only` build argument. When defining `GLM_FORCE_SINGLE_ONLY` before including GLM headers, GLM releases the requirement of double precision floating point values support. Effectivement, all the float64 types are no longer defined and double behaves like float.
This function returns a int however this function typically interacts with STL size\_t based code. GLM provides GLM\_FORCE\_SIZE\_T\_LENGTH pre-processor option so that member functions length() return a size\_t.
This function returns an`int` however this function typically interacts with STL `size_t` based code. GLM provides `GLM_FORCE_SIZE_T_LENGTH` pre-processor configuration so that member functions `length()` return a `size_t`.
Additionally, GLM defines the type glm::length\_t to identify length() returned type, independently from GLM\_FORCE\_SIZE\_T\_LENGTH.
Additionally, GLM defines the type `glm::length_t` to identify `length()` returned type, independently from `GLM_FORCE_SIZE_T_LENGTH`.
```cpp
#define GLM_FORCE_SIZE_T_LENGTH
@ -626,7 +627,7 @@ GLM 0.9.8 introduced GLM\_FORCE\_UNRESTRICTED\_GENTYPE define to relax this rest
typedef glm::vec<4,half> my_hvec4;
```
However, defining GLM\_FORCE\_UNRESTRICTED\_GENTYPE is not compatible with GLM\_FORCE\_SWIZZLE and will generate a compilation error if both are defined at the same time.
However, defining `GLM_FORCE_UNRESTRICTED\_GENTYPE` is not compatible with `GLM_FORCE_SWIZZLE` and will generate a compilation error if both are defined at the same time.
---
## <aname="section3"></a> 3. Stable extensions
@ -786,49 +787,49 @@ When an extension is included, all the dependent core functionalities and extens
Fast bitfield operations on scalar and vector variables.
<glm/gtc/bitfield.hpp> need to be included to use these features.
`<glm/gtc/bitfield.hpp>` need to be included to use these features.
@ -839,13 +840,13 @@ For example, the ***lookAt*** function generates a transformation matrix that pr
The matrices generated by this extension use standard OpenGL fixed-function conventions. For example, the ***lookAt*** function generates a transform from world space into the specific eye space that the
projective matrix functions (***perspective***, ***ortho***, etc) are designed to expect. The OpenGL compatibility specifications define the particular layout of this eye space.
<glm/gtc/matrix\_transform.hpp> need to be included to use these features.
`<glm/gtc/matrix_transform.hpp>` need to be included to use these features.
Convert scalar and vector types to and from packed formats, saving space at the cost of precision. However, packing a value into a format that it was previously unpacked from is guaranteed to be lossless.
<glm/gtc/packing.hpp> need to be included to use these features.
`<glm/gtc/packing.hpp>` need to be included to use these features.
Vector and matrix types with defined precisions, e.g. i8vec4, which is a 4D vector of signed 8-bit integers.
This extension adds defines to set the default precision of each class of types added, in a manner identical to that described in section [Default precision](#section3_1).
Available defines for signed 8-bit integer types (glm::i8vec\*):
* GLM\_PRECISION\_LOWP\_INT8: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT8: Medium precision
* GLM\_PRECISION\_HIGHP\_INT8: High precision (default)
Available defines for unsigned 8-bit integer types (glm::u8vec\*):
* GLM\_PRECISION\_LOWP\_UINT8: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT8: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT8: High precision (default)
Available defines for signed 16-bit integer types (glm::i16vec\*):
* GLM\_PRECISION\_LOWP\_INT16: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT16: Medium precision
* GLM\_PRECISION\_HIGHP\_INT16: High precision (default)
Available defines for unsigned 16-bit integer types (glm::u16vec\*):
* GLM\_PRECISION\_LOWP\_UINT16: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT16: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT16: High precision (default)
Available defines for signed 32-bit integer types (glm::i32vec\*):
* GLM\_PRECISION\_LOWP\_INT32: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT32: Medium precision
* GLM\_PRECISION\_HIGHP\_INT32: High precision (default)
Available defines for unsigned 32-bit integer types (glm::u32vec\*):
* GLM\_PRECISION\_LOWP\_UINT32: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT32: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT32: High precision (default)
Available defines for signed 64-bit integer types (glm::i64vec\*):
* GLM\_PRECISION\_LOWP\_INT64: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT64: Medium precision
* GLM\_PRECISION\_HIGHP\_INT64: High precision (default)
Available defines for unsigned 64-bit integer types (glm::u64vec\*):
* GLM\_PRECISION\_LOWP\_UINT64: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT64: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT64: High precision (default)
Available defines for 32-bit floating-point types (glm::f32vec\*, glm::f32mat\*, glm::f32quat):
* GLM\_PRECISION\_LOWP\_FLOAT32: Low precision
* GLM\_PRECISION\_MEDIUMP\_FLOAT32: Medium precision
* GLM\_PRECISION\_HIGHP\_FLOAT32: High precision (default)
Available defines for 64-bit floating-point types (glm::f64vec\*, glm::f64mat\*, glm::f64quat):
* GLM\_PRECISION\_LOWP\_FLOAT64: Low precision
* GLM\_PRECISION\_MEDIUMP\_FLOAT64: Medium precision
* GLM\_PRECISION\_HIGHP\_FLOAT64: High precision (default)
<glm/gtc/type\_precision.hpp> need to be included to use the features of this extension.
`<glm/gtc/type\_precision.hpp>` need to be included to use the features of this extension.
*Note: It would be possible to implement [*glVertex3fv*](http://www.opengl.org/sdk/docs/man2/xhtml/glVertex.xml)(glm::vec3(0)) in C++ with the appropriate cast operator that would result as an
implicit cast in this example. However cast operators may produce programs running with unexpected behaviours without build error or any form of notification. *
<glm/gtc/type\_ptr.hpp> need to be included to use these features.
`<glm/gtc/type_ptr.hpp>` need to be included to use these features.
### <aname="section4_19"></a> 4.19. GLM\_GTC\_ulp
Measure a function's accuracy given a reference implementation of it. This extension works on floating-point data and provides results in [ULP](http://ljk.imag.fr/membres/Carine.Lucas/TPScilab/JMMuller/ulp-toms.pdf).
<glm/gtc/ulp.hpp> need to be included to use these features.
`<glm/gtc/ulp.hpp>` need to be included to use these features.
From GLM\_GTC\_matrix\_transform extension: <glm/gtc/matrix\_transform.hpp>
From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>`
---
## <aname="section6"></a> 6. Known issues
@ -1214,7 +1153,7 @@ This section reports GLSL features that GLM can't accurately emulate due to lang
### <aname="section6_1"></a> 6.1. not function
The GLSL function 'not' is a keyword in C++. To prevent name collisions and ensure a consistent API, the name not\_ (note the underscore) is used instead.
The GLSL function 'not' is a keyword in C++. To prevent name collisions and ensure a consistent API, the name `not\_` (note the underscore) is used instead.
### <aname="section6_2"></a> 6.2. Precision qualifiers support
@ -1246,8 +1185,6 @@ ivec3 foo(const vec4 & v)
}
```
The syntax for default precision specifications in GLM differs from that in GLSL; for more information, see section Default Precision <aname="section3_1"></a>.
---
## <aname="section7"></a> 7. FAQ
@ -1297,8 +1234,8 @@ However, on performance critical code paths, we should expect that dedicated alg
### <aname="section7_9"></a> 7.9. When I build with Visual C++ with /W4 warning level, I have warnings...
You should not have any warnings even in /W4 mode. However, if you expect such level for your code, then you should ask for the same level to the compiler by at least disabling the Visual C++ language extensions
(/Za) which generates warnings when used. If these extensions are enabled, then GLM will take advantage of them and the compiler will generate warnings.
You should not have any warnings even in `/W4` mode. However, if you expect such level for your code, then you should ask for the same level to the compiler by at least disabling the Visual C++ language extensions
(`/Za`) which generates warnings when used. If these extensions are enabled, then GLM will take advantage of them and the compiler will generate warnings.
### <aname="section7_10"></a> 7.10. Why some GLM functions can crash because of division by zero?
@ -1312,13 +1249,13 @@ the [link](http://www.g-truc.net/post-0693.html#menu).
### <aname="section7_12"></a> 7.12. Windows headers cause build errors...
Some Windows headers define min and max as macros which may cause compatibility with third party libraries such as GLM.
It is highly recommended to [define NOMINMAX](http://stackoverflow.com/questions/4913922/possible-problems-with-nominmax-on-visual-c) before including Windows headers to workaround this issue.
It is highly recommended to [`define NOMINMAX`](http://stackoverflow.com/questions/4913922/possible-problems-with-nominmax-on-visual-c) before including Windows headers to workaround this issue.
To workaround the incompatibility with these macros, GLM will systematically undef these macros if they are defined.
### <aname="section7_13"></a> 7.13. Constant expressions support
GLM has some C++ <ahref="http://en.cppreference.com/w/cpp/language/constexpr">constant expressions</a> support. However, GLM automatically detects the use of SIMD instruction sets through compiler arguments to populate its implementation with SIMD intrinsics.
Unfortunately, GCC and Clang doesn't support SIMD instrinsics as constant expressions. To allow constant expressions on all vectors and matrices types, define GLM\_FORCE\_PURE before including GLM headers.
Unfortunately, GCC and Clang doesn't support SIMD instrinsics as constant expressions. To allow constant expressions on all vectors and matrices types, define `GLM_FORCE_PURE` before including GLM headers.