diff --git a/manual.md b/manual.md index 36f20d98..77d39c7c 100644 --- a/manual.md +++ b/manual.md @@ -245,7 +245,9 @@ glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, gl GLM does not depend on external libraries or headers such as ``, [``](http://www.opengl.org/registry/api/GL/glcorearb.h), ``, ``, or ``. --- -## 2. Swizzling +## 2. Preprocessor options + +### 2.1. GLM\_FORCE\_SWIZZLE: Enable swizzle operators Shader languages like GLSL often feature so-called swizzle expressions, which may be used to freely select and arrange a vector's components. For example, `variable.x`, `variable.xzy` and `variable.zxyy` respectively form a scalar, a 3D vector and a 4D vector. The result of a swizzle expression in GLSL can be either an R-value or an L-value. Swizzle expressions can be written with characters from exactly one of `xyzw` (usually for positions), `rgba` (usually for colors), and `stpq` (usually for texture coordinates). @@ -263,7 +265,7 @@ GLM optionally supports some of this functionality via the methods described in *Note that enabling swizzle expressions will massively increase the size of your binaries and the time it takes to compile them!* -### 2.1. Default C++98 implementation +### GLM\_FORCE\_SWIZZLE: Enable swizzle functions When compiling GLM as C++98, R-value swizzle expressions are simulated through member functions of each vector type. @@ -349,10 +351,89 @@ void foo() } ``` ---- -## 3. Preprocessor options +### 2.3. GLM\_FORCE\_XYZW\_ONLY: Only exposes x, y, z and w components -### 3.1. GLM\_PRECISION\_**: Default precision +TODO + +### 2.4. GLM\_FORCE\_MESSAGES: Compile-time message system + +GLM includes a notification system which can display some information at build time: + +* Platform: Windows, Linux, Native Client, QNX, etc. +* Compiler: Visual C++, Clang, GCC, ICC, etc. +* Build model: 32bits or 64 bits +* C++ version : C++98, C++11, MS extensions, etc. +* Architecture: x86, SSE, AVX, etc. +* Included extensions +* etc. + +This system is disabled by default. To enable this system, define GLM\_FORCE\_MESSAGES before any inclusion of <glm/glm.hpp>. The messages are generated only by compiler supporting \#program message and +only once per project build. + +```cpp +#define GLM_FORCE_MESSAGES +#include +``` + +### 2.5. 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: + +```cpp +#define GLM_FORCE_CXX98 +#include +``` + +For C++11 and C++14, equivalent defines are available: +GLM\_FORCE\_CXX11, GLM\_FORCE\_CXX14. + +```cpp +#define GLM_FORCE_CXX11 +#include + +// If the compiler doesn’t support C++11, compiler errors will happen. +``` + +GLM\_FORCE\_CXX14 overrides GLM\_FORCE\_CXX11 and GLM\_FORCE\_CXX11 +overrides GLM\_FORCE\_CXX98 defines. + +### 2.6. SIMD support + +GLM provides some SIMD optimizations based on [compiler intrinsics](https://msdn.microsoft.com/en-us/library/26td21ds.aspx). +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. + +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 +#include + +// GLM code will be compiled using pure C++ code without any intrinsics +``` + +```cpp +#define GLM_FORCE_AVX2 +#include + +// If the compiler doesn’t support AVX2 instrinsics, compiler errors will happen. +``` + +Additionally, GLM provides a low level SIMD API in glm/simd directory for users who are really interested in writing fast algorithms. + +### 2.7. GLM\_FORCE\_LEFT\_HANDED: Force left handed coordinate system + +TODO + +### 2.8. GLM\_FORCE\_DEPTH\_ZERO\_TO\_ONE: Force the use of a clip space between 0 to 1 + +TODO + +### 2.9. GLM\_PRECISION\_**: Default precision C++ does not provide a way to implement GLSL default precision selection (as defined in GLSL 4.10 specification section 4.5.3) with GLSL-like syntax. @@ -393,77 +474,7 @@ Available defines for unsigned integer types (glm::uvec\*): * GLM\_PRECISION\_MEDIUMP\_UINT: Medium precision * GLM\_PRECISION\_HIGHP\_UINT: High precision (default) -### 3.2. GLM\_FORCE\_MESSAGES: Compile-time message system - -GLM includes a notification system which can display some information at build time: - -* Platform: Windows, Linux, Native Client, QNX, etc. -* Compiler: Visual C++, Clang, GCC, ICC, etc. -* Build model: 32bits or 64 bits -* C++ version : C++98, C++11, MS extensions, etc. -* Architecture: x86, SSE, AVX, etc. -* Included extensions -* etc. - -This system is disabled by default. To enable this system, define GLM\_FORCE\_MESSAGES before any inclusion of <glm/glm.hpp>. The messages are generated only by compiler supporting \#program message and -only once per project build. - -```cpp -#define GLM_FORCE_MESSAGES -#include -``` - -### 3.3. 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: - -```cpp -#define GLM_FORCE_CXX98 -#include -``` - -For C++11 and C++14, equivalent defines are available: -GLM\_FORCE\_CXX11, GLM\_FORCE\_CXX14. - -```cpp -#define GLM_FORCE_CXX11 -#include - -// If the compiler doesn’t support C++11, compiler errors will happen. -``` - -GLM\_FORCE\_CXX14 overrides GLM\_FORCE\_CXX11 and GLM\_FORCE\_CXX11 -overrides GLM\_FORCE\_CXX98 defines. - -### 3.4. SIMD support - -GLM provides some SIMD optimizations based on [compiler intrinsics](https://msdn.microsoft.com/en-us/library/26td21ds.aspx). -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. - -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 -#include - -// GLM code will be compiled using pure C++ code without any intrinsics -``` - -```cpp -#define GLM_FORCE_AVX2 -#include - -// If the compiler doesn’t support AVX2 instrinsics, compiler errors will happen. -``` - -Additionally, GLM provides a low level SIMD API in glm/simd directory for users who are really interested in writing fast algorithms. - -### 3.5. GLM\_FORCE\_INLINE: Force inline +### 2.10. 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. @@ -472,7 +483,7 @@ To push further the software performance, a programmer can define GLM\_FORCE\_IN #include ``` -### 3.6. GLM\_FORCE\_SIZE\_T\_LENGTH: Vector and matrix static size +### 3.6. GLM\_FORCE\_SIZE\_T\_LENGTH: Vector and matrix static size GLSL supports the member function .length() for all vector and matrix types. @@ -501,7 +512,7 @@ void foo(vec4 const& v) } ``` -### 3.7. GLM\_FORCE\_EXPLICIT\_CTOR: Requiring explicit conversions +### 2.12. GLM\_FORCE\_EXPLICIT\_CTOR: Requiring explicit conversions GLSL supports implicit conversions of vector and matrix types. For example, an ivec4 can be implicitly converted into vec4. @@ -538,7 +549,7 @@ void foo() } ``` -### 3.8. GLM\_FORCE\_UNRESTRICTED\_GENTYPE: Removing genType restriction +### 2.13. GLM\_FORCE\_UNRESTRICTED\_GENTYPE: Removing genType restriction By default GLM only supports basic types as genType for vector, matrix and quaternion types: @@ -561,12 +572,149 @@ 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. -### 3.9. GLM\_FORCE\_SINGLE\_ONLY: Removed explicit 64-bits floating point types +### 2.14. 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. +### 2.15. GLM\_FORCE\_DEFAULT\_ALIGNED_GENTYPES: Force GLM to use aligned types by default + +TODO + +### 2.16. GLM_\FORCE\_PLATFORM\_UNKNOWN: Force GLM to no detect the build platform + +TODO + --- -## 4. Stable extensions +## 3. Stable extensions + +### 3.1. Scalar types + +TODO + +#### 3.1.1. GLM_EXT_scalar_float_sized + +TODO + +#### 3.1.2. GLM_EXT_scalar_int_sized + +TODO + +#### 3.1.3. GLM_EXT_scalar_uint_sized + +TODO + +### 3.2. Scalar functions + +#### 3.2.1. GLM_EXT_scalar_common + +TODO + +#### 3.2.2. GLM_EXT_scalar_relational + +TODO + +#### 3.2.3. GLM_EXT_scalar_constants + +TODO + +### 3.3. Vector types + +#### 3.3.1. GLM_EXT_vector_floatX(_precision) + +TODO + +#### 3.3.2. GLM_EXT_vector_doubleX(_precision) + +TODO + +#### 3.3.3. GLM_EXT_vector_intX(_precision) + +TODO + +#### 3.3.4. GLM_EXT_vector_uintX + +TODO + +#### 3.3.5. GLM_EXT_vector_boolX(_precision) + +TODO + +### 3.4. Vector functions + +### 3.22. GLM_EXT_vector_common + +TODO + +### 3.26. GLM_EXT_vector_relational + +TODO + +### 3.5. Matrix types + +#### 3.5.1. GLM_EXT_matrix_floatMxN(_precision) + +TODO + +#### 3.5.2. GLM_EXT_matrix_doubleMxN(_precision) + +TODO + +### 3.6. Matrix functions + +#### 3.6.1. GLM_EXT_matrix_relational + +TODO + +#### 3.6.2. GLM_EXT_matrix_transform + +TODO + +#### 3.6.3. GLM_EXT_matrix_clip_space + +TODO + +#### 3.6.4. GLM_EXT_matrix_projection + +TODO + +### 3.7. Quaternion types + +#### 3.7.1. GLM_EXT_quaternion_float(_precision) + +TODO + +#### 3.7.2. GLM_EXT_quaternion_double(_precision) + +TODO + +### 3.8. Quaternion functions + +3.8.1. GLM_EXT_quaternion_common + +TODO + +3.8.2. GLM_EXT_quaternion_geometric + +TODO + +3.8.3. GLM_EXT_quaternion_trigonometric + +TODO + +3.8.4. GLM_EXT_quaternion_exponential + +TODO + +3.8.5. GLM_EXT_quaternion_relation + +TODO + +3.8.6. GLM_EXT_quaternion_transform + +TODO + +--- +## 4. Recommended extensions GLM extends the core GLSL feature set with extensions. These extensions include: quaternion, transformation, spline, matrix inverse, color spaces, etc.