1![Alt](./doc/manual/logo-mini.png "GLM Logo") 2 3# GLM 0.9.9 Manual 4 5![Alt](./doc/manual/g-truc.png "G-Truc Logo") 6 7--- 8<div style="page-break-after: always;"> </div> 9 10## Table of Contents 11+ [0. Licenses](#section0) 12+ [1. Getting started](#section1) 13+ [1.1. Using global headers](#section1_1) 14+ [1.2. Using separated headers](#section1_2) 15+ [1.3. Using extension headers](#section1_3) 16+ [1.4. Dependencies](#section1_4) 17+ [1.5. Finding GLM with CMake](#section1_5) 18+ [2. Preprocessor configurations](#section2) 19+ [2.1. GLM\_FORCE\_MESSAGES: Platform auto detection and default configuration](#section2_1) 20+ [2.2. GLM\_FORCE\_PLATFORM\_UNKNOWN: Force GLM to no detect the build platform](#section2_2) 21+ [2.3. GLM\_FORCE\_COMPILER\_UNKNOWN: Force GLM to no detect the C++ compiler](#section2_3) 22+ [2.4. GLM\_FORCE\_ARCH\_UNKNOWN: Force GLM to no detect the build architecture](#section2_4) 23+ [2.5. GLM\_FORCE\_CXX\_UNKNOWN: Force GLM to no detect the C++ standard](#section2_5) 24+ [2.6. GLM\_FORCE\_CXX**: C++ language detection](#section2_6) 25+ [2.7. GLM\_FORCE\_EXPLICIT\_CTOR: Requiring explicit conversions](#section2_7) 26+ [2.8. GLM\_FORCE\_INLINE: Force inline](#section2_8) 27+ [2.9. GLM\_FORCE\_ALIGNED\_GENTYPES: Force GLM to enable aligned types](#section2_9) 28+ [2.10. GLM\_FORCE\_DEFAULT\_ALIGNED\_GENTYPES: Force GLM to use aligned types by default](#section2_10) 29+ [2.11. GLM\_FORCE\_INTRINSICS: Using SIMD optimizations](#section2_11) 30+ [2.12. GLM\_FORCE\_PRECISION\_**: Default precision](#section2_12) 31+ [2.13. GLM\_FORCE\_SINGLE\_ONLY: Removed explicit 64-bits floating point types](#section2_13) 32+ [2.14. GLM\_FORCE\_SWIZZLE: Enable swizzle operators](#section2_14) 33+ [2.15. GLM\_FORCE\_XYZW\_ONLY: Only exposes x, y, z and w components](#section2_15) 34+ [2.16. GLM\_FORCE\_LEFT\_HANDED: Force left handed coordinate system](#section2_16) 35+ [2.17. GLM\_FORCE\_DEPTH\_ZERO\_TO\_ONE: Force the use of a clip space between 0 to 1](#section2_17) 36+ [2.18. GLM\_FORCE\_SIZE\_T\_LENGTH: Vector and matrix static size type](#section2_18) 37+ [2.19. GLM\_FORCE\_UNRESTRICTED\_GENTYPE: Removing genType restriction](#section2_19) 38+ [2.20. GLM\_FORCE\_SILENT\_WARNINGS: Silent C++ warnings from language extensions](#section2_20) 39+ [2.21. GLM\_FORCE\_QUAT\_DATA\_WXYZ: Force GLM to store quat data as w,x,y,z instead of x,y,z,w](#section2_21) 40+ [3. Stable extensions](#section3) 41+ [3.1. Scalar types](#section3_1) 42+ [3.2. Scalar functions](#section3_2) 43+ [3.3. Vector types](#section3_3) 44+ [3.4. Vector types with precision qualifiers](#section3_4) 45+ [3.5. Vector functions](#section3_5) 46+ [3.6. Matrix types](#section3_6) 47+ [3.7. Matrix types with precision qualifiers](#section3_7) 48+ [3.8. Matrix functions](#section3_8) 49+ [3.9. Quaternion types](#section3_9) 50+ [3.10. Quaternion types with precision qualifiers](#section3_10) 51+ [3.11. Quaternion functions](#section3_11) 52+ [4. Recommended extensions](#section4) 53+ [4.1. GLM_GTC_bitfield](#section4_1) 54+ [4.2. GLM_GTC_color_space](#section4_2) 55+ [4.3. GLM_GTC_constants](#section4_3) 56+ [4.4. GLM_GTC_epsilon](#section4_4) 57+ [4.5. GLM_GTC_integer](#section4_5) 58+ [4.6. GLM_GTC_matrix_access](#section4_6) 59+ [4.7. GLM_GTC_matrix_integer](#section4_7) 60+ [4.8. GLM_GTC_matrix_inverse](#section4_8) 61+ [4.9. GLM_GTC_matrix_transform](#section4_9) 62+ [4.10. GLM_GTC_noise](#section4_10) 63+ [4.11. GLM_GTC_packing](#section4_11) 64+ [4.12. GLM_GTC_quaternion](#section4_12) 65+ [4.13. GLM_GTC_random](#section4_13) 66+ [4.14. GLM_GTC_reciprocal](#section4_14) 67+ [4.15. GLM_GTC_round](#section4_15) 68+ [4.16. GLM_GTC_type_alignment](#section4_16) 69+ [4.17. GLM_GTC_type_precision](#section4_17) 70+ [4.18. GLM_GTC_type_ptr](#section4_18) 71+ [4.19. GLM_GTC_ulp](#section4_19) 72+ [4.20. GLM_GTC_vec1](#section4_20) 73+ [5. OpenGL interoperability](#section5) 74+ [5.1. GLM Replacements for deprecated OpenGL functions](#section5_1) 75+ [5.2. GLM Replacements for GLU functions](#section5_2) 76+ [6. Known issues](#section6) 77+ [6.1. Not function](#section6_1) 78+ [6.2. Precision qualifiers support](#section6_2) 79+ [7. FAQ](#section7) 80+ [7.1 Why GLM follows GLSL specification and conventions?](#section7_1) 81+ [7.2. Does GLM run GLSL programs?](#section7_2) 82+ [7.3. Does a GLSL compiler build GLM codes?](#section7_3) 83+ [7.4. Should I use ‘GTX’ extensions?](#section7_4) 84+ [7.5. Where can I ask my questions?](#section7_5) 85+ [7.6. Where can I find the documentation of extensions?](#section7_6) 86+ [7.7. Should I use 'using namespace glm;'?](#section7_7) 87+ [7.8. Is GLM fast?](#section7_8) 88+ [7.9. When I build with Visual C++ with /w4 warning level, I have warnings...](#section7_9) 89+ [7.10. Why some GLM functions can crash because of division by zero?](#section7_10) 90+ [7.11. What unit for angles us used in GLM?](#section7_11) 91+ [7.12. Windows headers cause build errors...](#section7_12) 92+ [7.13. Constant expressions support](#section7_13) 93+ [8. Code samples](#section8) 94+ [8.1. Compute a triangle normal](#section8_1) 95+ [8.2. Matrix transform](#section8_2) 96+ [8.3. Vector types](#section8_3) 97+ [8.4. Lighting](#section8_4) 98+ [9. Contributing to GLM](#section9) 99+ [9.1. Submitting bug reports](#section9_1) 100+ [9.2. Contributing to GLM with pull request](#section9_2) 101+ [9.3. Coding style](#section9_3) 102+ [10. References](#section10) 103+ [10.1. OpenGL specifications](#section10_1) 104+ [10.2. External links](#section10_2) 105+ [10.3. Projects using GLM](#section10_3) 106+ [10.4. Tutorials using GLM](#section10_4) 107+ [10.5. Equivalent for other languages](#section10_5) 108+ [10.6. Alternatives to GLM](#section10_6) 109+ [10.7. Acknowledgements](#section10_7) 110 111--- 112<div style="page-break-after: always;"> </div> 113 114## <a name="section0"></a> Licenses 115 116### The Happy Bunny License (Modified MIT License) 117 118Copyright (c) 2005 - G-Truc Creation 119 120Permission is hereby granted, free of charge, to any person obtaining a 121copy of this software and associated documentation files (the 122"Software"), to deal in the Software without restriction, including 123without limitation the rights to use, copy, modify, merge, publish, 124distribute, sublicense, and/or sell copies of the Software, and to 125permit persons to whom the Software is furnished to do so, subject to 126the following conditions: 127 128The above copyright notice and this permission notice shall be included 129in all copies or substantial portions of the Software. 130 131Restrictions: By making use of the Software for military purposes, you 132choose to make a Bunny unhappy. 133 134THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 135OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 136MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 137IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 138CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 139TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 140SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 141 142![](./doc/manual/frontpage1.png) 143 144### The MIT License 145 146Copyright (c) 2005 - G-Truc Creation 147 148Permission is hereby granted, free of charge, to any person obtaining a 149copy of this software and associated documentation files (the 150"Software"), to deal in the Software without restriction, including 151without limitation the rights to use, copy, modify, merge, publish, 152distribute, sublicense, and/or sell copies of the Software, and to 153permit persons to whom the Software is furnished to do so, subject to 154the following conditions: 155 156The above copyright notice and this permission notice shall be included 157in all copies or substantial portions of the Software. 158 159THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 160OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 161MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 162IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 163CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 164TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 165SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 166 167![](./doc/manual/frontpage2.png) 168 169--- 170<div style="page-break-after: always;"> </div> 171 172## <a name="section1"></a> 1. Getting started 173### <a name="section1_1"></a> 1.1. Using global headers 174 175GLM is a header-only library, and thus does not need to be compiled. We can use GLM's implementation of GLSL's mathematics functionality by including the `<glm/glm.hpp>` header: 176 177```cpp 178#include <glm/glm.hpp> 179``` 180 181To extend the feature set supported by GLM and keeping the library as close to GLSL as possible, new features are implemented as extensions that can be included thought a separated header: 182```cpp 183// Include all GLM core / GLSL features 184#include <glm/glm.hpp> // vec2, vec3, mat4, radians 185 186// Include all GLM extensions 187#include <glm/ext.hpp> // perspective, translate, rotate 188 189glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, glm::vec3 const& Up) 190{ 191 glm::mat4 Proj = glm::perspective(glm::radians(45.f), 1.33f, 0.1f, 10.f); 192 glm::mat4 ViewTranslate = glm::translate(glm::mat4(1.f), Translate); 193 glm::mat4 ViewRotateX = glm::rotate(ViewTranslate, Orientation.y, Up); 194 glm::mat4 View = glm::rotate(ViewRotateX, Orientation.x, Up); 195 glm::mat4 Model = glm::mat4(1.0f); 196 return Proj * View * Model; 197} 198``` 199 200*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.* 201 202### <a name="section1_2"></a> 1.2. Using separated headers 203 204GLM relies on C++ templates heavily, and may significantly increase compilation times for projects that use it. Hence, user projects could only include the features they actually use. Following is the list of all the core features, based on GLSL specification, headers: 205```cpp 206#include <glm/vec2.hpp> // vec2, bvec2, dvec2, ivec2 and uvec2 207#include <glm/vec3.hpp> // vec3, bvec3, dvec3, ivec3 and uvec3 208#include <glm/vec4.hpp> // vec4, bvec4, dvec4, ivec4 and uvec4 209#include <glm/mat2x2.hpp> // mat2, dmat2 210#include <glm/mat2x3.hpp> // mat2x3, dmat2x3 211#include <glm/mat2x4.hpp> // mat2x4, dmat2x4 212#include <glm/mat3x2.hpp> // mat3x2, dmat3x2 213#include <glm/mat3x3.hpp> // mat3, dmat3 214#include <glm/mat3x4.hpp> // mat3x4, dmat2 215#include <glm/mat4x2.hpp> // mat4x2, dmat4x2 216#include <glm/mat4x3.hpp> // mat4x3, dmat4x3 217#include <glm/mat4x4.hpp> // mat4, dmat4 218#include <glm/common.hpp> // all the GLSL common functions: abs, min, mix, isnan, fma, etc. 219#include <glm/exponential.hpp> // all the GLSL exponential functions: pow, log, exp2, sqrt, etc. 220#include <glm/geometry.hpp> // all the GLSL geometry functions: dot, cross, reflect, etc. 221#include <glm/integer.hpp> // all the GLSL integer functions: findMSB, bitfieldExtract, etc. 222#include <glm/matrix.hpp> // all the GLSL matrix functions: transpose, inverse, etc. 223#include <glm/packing.hpp> // all the GLSL packing functions: packUnorm4x8, unpackHalf2x16, etc. 224#include <glm/trigonometric.hpp> // all the GLSL trigonometric functions: radians, cos, asin, etc. 225#include <glm/vector_relational.hpp> // all the GLSL vector relational functions: equal, less, etc. 226``` 227 228The following is a code sample using separated core headers and an extension: 229```cpp 230// Include GLM core features 231#include <glm/vec2.hpp> // vec2 232#include <glm/vec3.hpp> // vec3 233#include <glm/mat4x4.hpp> // mat4 234#include <glm/trigonometric.hpp> //radians 235 236// Include GLM extension 237#include <glm/ext/matrix_transform.hpp> // perspective, translate, rotate 238 239glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, glm::vec3 const& Up) 240{ 241 glm::mat4 Proj = glm::perspective(glm::radians(45.f), 1.33f, 0.1f, 10.f); 242 glm::mat4 ViewTranslate = glm::translate(glm::mat4(1.f), Translate); 243 glm::mat4 ViewRotateX = glm::rotate(ViewTranslate, Orientation.y, Up); 244 glm::mat4 View = glm::rotate(ViewRotateX, Orientation.x, Up); 245 glm::mat4 Model = glm::mat4(1.0f); 246 return Proj * View * Model; 247} 248``` 249 250### <a name="section1_3"></a> 1.3. Using extension headers 251 252Using GLM through split headers to minimize the project build time: 253```cpp 254// Include GLM vector extensions: 255#include <glm/ext/vector_float2.hpp> // vec2 256#include <glm/ext/vector_float3.hpp> // vec3 257#include <glm/ext/vector_trigonometric.hpp> // radians 258 259// Include GLM matrix extensions: 260#include <glm/ext/matrix_float4x4.hpp> // mat4 261#include <glm/ext/matrix_transform.hpp> // perspective, translate, rotate 262 263glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, glm::vec3 const& Up) 264{ 265 glm::mat4 Proj = glm::perspective(glm::radians(45.f), 1.33f, 0.1f, 10.f); 266 glm::mat4 ViewTranslate = glm::translate(glm::mat4(1.f), Translate); 267 glm::mat4 ViewRotateX = glm::rotate(ViewTranslate, Orientation.y, Up); 268 glm::mat4 View = glm::rotate(ViewRotateX, Orientation.x, Up); 269 glm::mat4 Model = glm::mat4(1.0f); 270 return Proj * View * Model; 271} 272``` 273 274### <a name="section1_4"></a> 1.4. Dependencies 275 276GLM does not depend on external libraries or headers such as `<GL/gl.h>`, [`<GL/glcorearb.h>`](http://www.opengl.org/registry/api/GL/glcorearb.h), `<GLES3/gl3.h>`, `<GL/glu.h>`, or `<windows.h>`. 277 278### <a name="section1_5"></a> 1.5. Finding GLM with CMake 279 280GLM packages a `glmConfig.cmake` and `glmConfig-version.cmake` in the root of the repository and the release archives. To find GLM with CMake you can pass `-Dglm_DIR=<path to glm root>/cmake/glm/` when running CMake. You can then either add `${GLM_INCLUDE_DIRS}` to your target's include directories, or link against the imported `glm::glm` target. 281 282--- 283<div style="page-break-after: always;"> </div> 284 285## <a name="section2"></a> 2. Preprocessor configurations 286 287### <a name="section2_1"></a> 2.1. GLM\_FORCE\_MESSAGES: Platform auto detection and default configuration 288 289When included, GLM will first automatically detect the compiler used, the C++ standard supported, the compiler arguments used to configure itself matching the build environment. 290 291For example, if the compiler arguments request AVX code generation, GLM will rely on its code path providing AVX optimizations when available. 292 293We can change GLM configuration using specific C++ preprocessor defines that must be declared before including any GLM headers. 294 295Using `GLM_FORCE_MESSAGES`, GLM will report the configuration as part of the build log. 296 297```cpp 298#define GLM_FORCE_MESSAGES // Or defined when building (e.g. -DGLM_FORCE_SWIZZLE) 299#include <glm/glm.hpp> 300``` 301 302Example of configuration log generated by `GLM_FORCE_MESSAGES`: 303```cpp 304GLM: version 0.9.9.1 305GLM: C++ 17 with extensions 306GLM: Clang compiler detected 307GLM: x86 64 bits with AVX instruction set build target 308GLM: Linux platform detected 309GLM: GLM_FORCE_SWIZZLE is undefined. swizzling functions or operators are disabled. 310GLM: GLM_FORCE_SIZE_T_LENGTH is undefined. .length() returns a glm::length_t, a typedef of int following GLSL. 311GLM: GLM_FORCE_UNRESTRICTED_GENTYPE is undefined. Follows strictly GLSL on valid function genTypes. 312GLM: GLM_FORCE_DEPTH_ZERO_TO_ONE is undefined. Using negative one to one depth clip space. 313GLM: GLM_FORCE_LEFT_HANDED is undefined. Using right handed coordinate system. 314``` 315 316The following subsections describe each configurations and defines. 317 318### <a name="section2_2"></a> 2.2. GLM\_FORCE\_PLATFORM\_UNKNOWN: Force GLM to no detect the build platform 319 320`GLM_FORCE_PLATFORM_UNKNOWN` prevents GLM from detecting the build platform. 321 322### <a name="section2_3"></a> 2.3. GLM\_FORCE\_COMPILER\_UNKNOWN: Force GLM to no detect the C++ compiler 323 324`GLM_FORCE_COMPILER_UNKNOWN` prevents GLM from detecting the C++ compiler. 325 326### <a name="section2_4"></a> 2.4. GLM\_FORCE\_ARCH\_UNKNOWN: Force GLM to no detect the build architecture 327 328`GLM_FORCE_ARCH_UNKNOWN` prevents GLM from detecting the build target architecture. 329 330### <a name="section2_5"></a> 2.5. GLM\_FORCE\_CXX\_UNKNOWN: Force GLM to no detect the C++ standard 331 332`GLM_FORCE_CSS_UNKNOWN` prevents GLM from detecting the C++ compiler standard support. 333 334### <a name="section2_6"></a> 2.6. GLM\_FORCE\_CXX**: C++ language detection 335 336GLM 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 337any inclusion of `<glm/glm.hpp>` to restrict the language feature set C++98: 338 339```cpp 340#define GLM_FORCE_CXX98 341#include <glm/glm.hpp> 342``` 343 344For C++11, C++14, and C++17 equivalent defines are available: 345* `GLM_FORCE_CXX11` 346* `GLM_FORCE_CXX14` 347* `GLM_FORCE_CXX17` 348 349```cpp 350#define GLM_FORCE_CXX11 351#include <glm/glm.hpp> 352 353// If the compiler doesn’t support C++11, compiler errors will happen. 354``` 355 356`GLM_FORCE_CXX17` overrides `GLM_FORCE_CXX14`; `GLM_FORCE_CXX14` overrides `GLM_FORCE_CXX11`; and `GLM_FORCE_CXX11` overrides `GLM_FORCE_CXX98` defines. 357 358### <a name="section2_7"></a> 2.7. GLM\_FORCE\_EXPLICIT\_CTOR: Requiring explicit conversions 359 360GLSL supports implicit conversions of vector and matrix types. For example, an ivec4 can be implicitly converted into `vec4`. 361 362Often, 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. 363 364```cpp 365#include <glm/glm.hpp> 366 367void foo() 368{ 369 glm::ivec4 a; 370 ... 371 372 glm::vec4 b(a); // Explicit conversion, OK 373 glm::vec4 c = a; // Implicit conversion, OK 374 ... 375} 376``` 377 378With `GLM_FORCE_EXPLICIT_CTOR` define, implicit conversions are not allowed: 379 380```cpp 381#define GLM_FORCE_EXPLICIT_CTOR 382#include <glm/glm.hpp> 383 384void foo() 385{ 386 glm::ivec4 a; 387 { 388 glm::vec4 b(a); // Explicit conversion, OK 389 glm::vec4 c = a; // Implicit conversion, ERROR 390 ... 391} 392``` 393 394### <a name="section2_8"></a> 2.8. GLM\_FORCE\_INLINE: Force inline 395 396To 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. 397 398```cpp 399#define GLM_FORCE_INLINE 400#include <glm/glm.hpp> 401``` 402 403### <a name="section2_9"></a> 2.9. GLM\_FORCE\_ALIGNED\_GENTYPES: Force GLM to enable aligned types 404 405Every object type has the property called alignment requirement, which is an integer value (of type `std::size_t`, always a power of 2) representing the number of bytes between successive addresses at which objects of this type can be allocated. The alignment requirement of a type can be queried with alignof or `std::alignment_of`. The pointer alignment function `std::align` can be used to obtain a suitably-aligned pointer within some buffer, and `std::aligned_storage` can be used to obtain suitably-aligned storage. 406 407Each object type imposes its alignment requirement on every object of that type; stricter alignment (with larger alignment requirement) can be requested using C++11 `alignas`. 408 409In order to satisfy alignment requirements of all non-static members of a class, padding may be inserted after some of its members. 410 411GLM supports both packed and aligned types. Packed types allow filling data structure without inserting extra padding. Aligned GLM types align addresses based on the size of the value type of a GLM type. 412 413```cpp 414#define GLM_FORCE_ALIGNED_GENTYPES 415#include <glm/glm.hpp> 416#include <glm/gtc/type_aligned.hpp> 417 418typedef glm::aligned_vec4 vec4a; 419typedef glm::packed_vec4 vec4p; 420``` 421 422### <a name="section2_10"></a> 2.10. GLM\_FORCE\_DEFAULT\_ALIGNED\_GENTYPES: Force GLM to use aligned types by default 423 424GLM allows using aligned types by default for vector types using `GLM_FORCE_DEFAULT_ALIGNED_GENTYPES`: 425 426```cpp 427#define GLM_FORCE_DEFAULT_ALIGNED_GENTYPES 428#include <glm/glm.hpp> 429 430struct MyStruct 431{ 432 glm::vec4 a; 433 float b; 434 glm::vec3 c; 435}; 436 437void foo() 438{ 439 printf("MyStruct requires memory padding: %d bytes\n", sizeof(MyStruct)); 440} 441 442>>> MyStruct requires memory padding: 48 bytes 443``` 444 445```cpp 446#include <glm/glm.hpp> 447 448struct MyStruct 449{ 450 glm::vec4 a; 451 float b; 452 glm::vec3 c; 453}; 454 455void foo() 456{ 457 printf("MyStruct is tightly packed: %d bytes\n", sizeof(MyStruct)); 458} 459 460>>> MyStruct is tightly packed: 32 bytes 461``` 462 463*Note: GLM SIMD optimizations require the use of aligned types* 464 465### <a name="section2_11"></a> 2.11. GLM\_FORCE\_INTRINSICS: Using SIMD optimizations 466 467GLM provides some SIMD optimizations based on [compiler intrinsics](https://msdn.microsoft.com/en-us/library/26td21ds.aspx). 468These optimizations will be automatically thanks to compiler arguments when `GLM_FORCE_INTRINSICS` is defined before including GLM files. 469For 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. 470 471It’s possible to avoid the instruction set detection by forcing the use of a specific instruction set with one of the fallowing define: 472`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`. 473 474The use of intrinsic functions by GLM implementation can be avoided using the define `GLM_FORCE_PURE` before any inclusion of GLM headers. This can be particularly useful if we want to rely on C++14 `constexpr`. 475 476```cpp 477#define GLM_FORCE_PURE 478#include <glm/glm.hpp> 479 480static_assert(glm::vec4::length() == 4, "Using GLM C++ 14 constexpr support for compile time tests"); 481 482// GLM code will be compiled using pure C++ code without any intrinsics 483``` 484 485```cpp 486#define GLM_FORCE_SIMD_AVX2 487#include <glm/glm.hpp> 488 489// If the compiler doesn’t support AVX2 instrinsics, compiler errors will happen. 490``` 491 492Additionally, GLM provides a low level SIMD API in glm/simd directory for users who are really interested in writing fast algorithms. 493 494### <a name="section2_12"></a> 2.12. GLM\_FORCE\_PRECISION\_**: Default precision 495 496C++ 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. 497 498```glsl 499precision mediump int; 500precision highp float; 501``` 502 503To use the default precision functionality, GLM provides some defines that need to added before any include of `glm.hpp`: 504 505```cpp 506#define GLM_FORCE_PRECISION_MEDIUMP_INT 507#define GLM_FORCE_PRECISION_HIGHP_FLOAT 508#include <glm/glm.hpp> 509``` 510 511Available defines for floating point types (`glm::vec\*`, `glm::mat\*`): 512 513* `GLM_FORCE_PRECISION_LOWP_FLOAT`: Low precision 514* `GLM_FORCE_PRECISION_MEDIUMP_FLOAT`: Medium precision 515* `GLM_FORCE_PRECISION_HIGHP_FLOAT`: High precision (default) 516 517Available defines for floating point types (`glm::dvec\*`, `glm::dmat\*`): 518 519* `GLM_FORCE_PRECISION_LOWP_DOUBLE`: Low precision 520* `GLM_FORCE_PRECISION_MEDIUMP_DOUBLE`: Medium precision 521* `GLM_FORCE_PRECISION_HIGHP_DOUBLE`: High precision (default) 522 523Available defines for signed integer types (`glm::ivec\*`): 524 525* `GLM_FORCE_PRECISION_LOWP_INT`: Low precision 526* `GLM_FORCE_PRECISION_MEDIUMP_INT`: Medium precision 527* `GLM_FORCE_PRECISION_HIGHP_INT`: High precision (default) 528 529Available defines for unsigned integer types (`glm::uvec\*`): 530 531* `GLM_FORCE_PRECISION_LOWP_UINT`: Low precision 532* `GLM_FORCE_PRECISION_MEDIUMP_UINT`: Medium precision 533* `GLM_FORCE_PRECISION_HIGHP_UINT`: High precision (default) 534 535### <a name="section2_13"></a> 2.13. GLM\_FORCE\_SINGLE\_ONLY: Removed explicit 64-bits floating point types 536 537Some 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. 538 539### <a name="section2_14"></a> 2.14. GLM\_FORCE\_SWIZZLE: Enable swizzle operators 540 541Shader 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). 542 543```glsl 544vec4 A; 545vec2 B; 546 547B.yx = A.wy; 548B = A.xx; 549vec3 C = A.bgr; 550vec3 D = B.rsz; // Invalid, won't compile 551``` 552 553GLM supports some of this functionality. Swizzling can be enabled by defining `GLM_FORCE_SWIZZLE`. 554 555*Note: Enabling swizzle expressions will massively increase the size of your binaries and the time it takes to compile them!* 556 557GLM has two levels of swizzling support described in the following subsections. 558 559#### 2.14.1. Swizzle functions for standard C++ 98 560 561When compiling GLM as C++98, R-value swizzle expressions are simulated through member functions of each vector type. 562 563```cpp 564#define GLM_FORCE_SWIZZLE // Or defined when building (e.g. -DGLM_FORCE_SWIZZLE) 565#include <glm/glm.hpp> 566 567void foo() 568{ 569 glm::vec4 const ColorRGBA = glm::vec4(1.0f, 0.5f, 0.0f, 1.0f); 570 glm::vec3 const ColorBGR = ColorRGBA.bgr(); 571 572 glm::vec3 const PositionA = glm::vec3(1.0f, 0.5f, 0.0f); 573 glm::vec3 const PositionB = PositionXYZ.xyz() * 2.0f; 574 575 glm::vec2 const TexcoordST = glm::vec2(1.0f, 0.5f); 576 glm::vec4 const TexcoordSTPQ = TexcoordST.stst(); 577} 578``` 579 580Swizzle operators return a **copy** of the component values, and thus *can't* be used as L-values to change a vector's values. 581 582```cpp 583#define GLM_FORCE_SWIZZLE 584#include <glm/glm.hpp> 585 586void foo() 587{ 588 glm::vec3 const A = glm::vec3(1.0f, 0.5f, 0.0f); 589 590 // No compiler error, but A is not modified. 591 // An anonymous copy is being modified (and then discarded). 592 A.bgr() = glm::vec3(2.0f, 1.5f, 1.0f); // A is not modified! 593} 594``` 595 596#### 2.14.2. Swizzle operations for C++ 98 with language extensions 597 598Visual C++, GCC and Clang support, as a _non-standard language extension_, anonymous `struct`s as `union` members. This permits a powerful swizzling implementation that both allows L-value swizzle expressions and GLSL-like syntax. To use this feature, the language extension must be enabled by a supporting compiler and `GLM_FORCE_SWIZZLE` must be `#define`d. 599 600```cpp 601#define GLM_FORCE_SWIZZLE 602#include <glm/glm.hpp> 603 604// Only guaranteed to work with Visual C++! 605// Some compilers that support Microsoft extensions may compile this. 606void foo() 607{ 608 glm::vec4 ColorRGBA = glm::vec4(1.0f, 0.5f, 0.0f, 1.0f); 609 610 // l-value: 611 glm::vec4 ColorBGRA = ColorRGBA.bgra; 612 613 // r-value: 614 ColorRGBA.bgra = ColorRGBA; 615 616 // Both l-value and r-value 617 ColorRGBA.bgra = ColorRGBA.rgba; 618} 619``` 620 621This version returns implementation-specific objects that _implicitly convert_ to their respective vector types. As a consequence of this design, these extra types **can't be directly used** as C++ function arguments; they must be converted through constructors or `operator()`. 622 623```cpp 624#define GLM_FORCE_SWIZZLE 625#include <glm/glm.hpp> 626 627using namespace glm; 628 629void foo() 630{ 631 vec4 Color = vec4(1.0f, 0.5f, 0.0f, 1.0f); 632 633 // Generates compiler errors. Color.rgba is not a vector type. 634 vec4 ClampedA = clamp(Color.rgba, 0.f, 1.f); // ERROR 635 636 // Explicit conversion through a constructor 637 vec4 ClampedB = clamp(vec4(Color.rgba), 0.f, 1.f); // OK 638 639 // Explicit conversion through operator() 640 vec4 ClampedC = clamp(Color.rgba(), 0.f, 1.f); // OK 641} 642``` 643 644*Note: The implementation has a caveat: Swizzle operator types must be different on both size of the equal operator or the operation will fail. There is no known fix for this issue to date* 645 646### <a name="section2_15"></a> 2.15. GLM\_FORCE\_XYZW\_ONLY: Only exposes x, y, z and w components 647 648Following GLSL specifications, GLM supports three sets of components to access vector types member: x, y, z, w; r, g, b, a; and s, t, p, q. 649Also, this is making vector component very expressive in the code, it may make debugging vector types a little cubersom as the debuggers will typically display three time the values for each compoenents due to the existence of the three sets. 650 651To simplify vector types, GLM allows exposing only x, y, z and w components thanks to `GLM_FORCE_XYZW_ONLY` define. 652 653### <a name="section2_16"></a> 2.16. GLM\_FORCE\_LEFT\_HANDED: Force left handed coordinate system 654 655By default, OpenGL is using a right handed coordinate system. However, others APIs such as Direct3D have done different choice and relies on the left handed coordinate system. 656 657GLM allows switching the coordinate system to left handed by defining `GLM_FORCE_LEFT_HANDED`. 658 659### <a name="section2_17"></a> 2.17. GLM\_FORCE\_DEPTH\_ZERO\_TO\_ONE: Force the use of a clip space between 0 to 1 660 661By default, OpenGL is using a -1 to 1 clip space in Z-axis. However, others APIs such as Direct3D relies on a clip space between 0 to 1 in Z-axis. 662 663GLM allows switching the clip space in Z-axis to 0 to 1 by defining `GLM_FORCE_DEPTH_ZERO_TO_ONE`. 664 665### <a name="section2_18"></a> 2.18. GLM\_FORCE\_SIZE\_T\_LENGTH: Vector and matrix static size 666 667GLSL supports the member function .length() for all vector and matrix types. 668 669```cpp 670#include <glm/glm.hpp> 671 672void foo(vec4 const& v) 673{ 674 int Length = v.length(); 675 ... 676} 677``` 678 679This 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`. 680 681Additionally, GLM defines the type `glm::length_t` to identify `length()` returned type, independently from `GLM_FORCE_SIZE_T_LENGTH`. 682 683```cpp 684#define GLM_FORCE_SIZE_T_LENGTH 685#include <glm/glm.hpp> 686 687void foo(vec4 const& v) 688{ 689 glm::length_t Length = v.length(); 690 ... 691} 692``` 693 694### <a name="section2_19"></a> 2.19. GLM\_FORCE\_UNRESTRICTED\_GENTYPE: Removing genType restriction 695 696GLSL has restrictions on types supported by certain functions that may appear excessive. 697By default, GLM follows the GLSL specification as accurately as possible however it's possible to relax these rules using `GLM_FORCE_UNRESTRICTED_GENTYPE` define. 698 699```cpp 700#include <glm/glm.hpp> 701 702float average(float const A, float const B) 703{ 704 return glm::mix(A, B, 0.5f); // By default glm::mix only supports floating-point types 705} 706``` 707 708By defining GLM\_FORCE\_UNRESTRICTED\_GENTYPE, we allow using integer types: 709 710```cpp 711#define GLM_FORCE_UNRESTRICTED_GENTYPE 712#include <glm/glm.hpp> 713 714int average(int const A, int const B) 715{ 716 return glm::mix(A, B, 0.5f); // integers are ok thanks to GLM_FORCE_UNRESTRICTED_GENTYPE 717} 718``` 719 720### <a name="section2_20"></a> 2.20. GLM\_FORCE\_SILENT\_WARNINGS: Silent C++ warnings from language extensions 721 722When using /W4 on Visual C++ or -Wpedantic on GCC, for example, the compilers will generate warnings for using C++ language extensions (/Za with Visual C++) such as anonymous struct. 723GLM relies on anonymous structs for swizzle operators and aligned vector types. To silent those warnings define `GLM_FORCE_SILENT_WARNINGS` before including GLM headers. 724 725 726### <a name="section2_21"></a> 2.21. GLM\_FORCE\_QUAT\_DATA\_WXYZ: Force GLM to store quat data as w,x,y,z instead of x,y,z,w 727 728By default GLM store quaternion components with the x, y, z, w order. `GLM_FORCE_QUAT_DATA_WXYZ` allows switching the quaternion data storage to the w, x, y, z order. 729 730--- 731<div style="page-break-after: always;"> </div> 732 733## <a name="section3"></a> 3. Stable extensions 734 735### <a name="section3_1"></a> 3.1. Scalar types 736 737#### 3.1.1. GLM_EXT_scalar_int_sized 738 739This extension exposes sized and signed integer types. 740 741Include `<glm/ext/scalar_int_sized.hpp>` to use these features. 742 743#### 3.1.2. GLM_EXT_scalar_uint_sized 744 745This extension exposes sized and unsigned integer types. 746 747```cpp 748#include <glm/ext/scalar_common.hpp> 749 750glm::uint64 pack(glm::uint32 A, glm::uint16 B, glm::uint8 C, glm::uint8 D) 751{ 752 glm::uint64 ShiftA = 0; 753 glm::uint64 ShiftB = sizeof(glm::uint32) * 8; 754 glm::uint64 ShiftC = (sizeof(glm::uint32) + sizeof(glm::uint16)) * 8; 755 glm::uint64 ShiftD = (sizeof(glm::uint32) + sizeof(glm::uint16) + sizeof(glm::uint8)) * 8; 756 return (glm::uint64(A) << ShiftA) | (glm::uint64(B) << ShiftB) | (glm::uint64(C) << ShiftC) | (glm::uint64(D) << ShiftD); 757} 758``` 759 760Include `<glm/ext/scalar_uint_sized.hpp>` to use these features. 761 762### <a name="section3_2"></a> 3.2. Scalar functions 763 764#### 3.2.1. GLM_EXT_scalar_common 765 766This extension exposes support for `min` and `max` functions taking more than two scalar arguments. Also, it adds `fmin` and `fmax` variants which prevents `NaN` propagation. 767 768```cpp 769#include <glm/ext/scalar_common.hpp> 770 771float positiveMax(float const a, float const b) 772{ 773 return glm::fmax(a, b, 0.0f); 774} 775``` 776 777Include `<glm/ext/scalar_common.hpp>` to use these features. 778 779#### 3.2.2. GLM_EXT_scalar_relational 780 781This extension exposes `equal` and `notEqual` scalar variants which takes an epsilon argument. 782 783```cpp 784#include <glm/ext/scalar_relational.hpp> 785 786bool epsilonEqual(float const a, float const b) 787{ 788 float const CustomEpsilon = 0.0001f; 789 return glm::equal(a, b, CustomEpsilon); 790} 791``` 792 793Include `<glm/ext/scalar_relational.hpp>` to use these features. 794 795#### 3.2.3. GLM_EXT_scalar_constants 796 797This extension exposes useful constants such as `epsilon` and `pi`. 798 799```cpp 800#include <glm/ext/scalar_constants.hpp> 801 802float circumference(float const Diameter) 803{ 804 return glm::pi<float>() * Diameter; 805} 806``` 807 808```cpp 809#include <glm/common.hpp> // abs 810#include <glm/ext/scalar_constants.hpp> // epsilon 811 812bool equalULP1(float const a, float const b) 813{ 814 return glm::abs(a - b) <= glm::epsilon<float>(); 815} 816``` 817 818Include `<glm/ext/scalar_constants.hpp>` to use these features. 819 820#### 3.2.4. GLM_EXT_scalar_ulp 821 822This extension exposes function that measure of accuracy in numeric calculations. 823 824```cpp 825#include <glm/ext/scalar_ulp.hpp> 826 827bool test_ulp(float x) 828{ 829 float const a = glm::next_float(x); // return a float a ULP away from the float argument. 830 return float_distance(a, x) == 1; // check both float are a single ULP away. 831} 832``` 833 834Include `<glm/ext/scalar_ulp.hpp>` to use these features. 835 836### <a name="section3_3"></a> 3.3. Vector types 837 838#### 3.3.1. GLM_EXT_vector_float1 839 840This extension exposes single-precision floating point vector with 1 component: `vec1`. 841 842Include `<glm/ext/vector_float1.hpp>` to use these features. 843 844#### 3.3.2. GLM_EXT_vector_float2 845 846This extension exposes single-precision floating point vector with 2 components: `vec2`. 847 848Include `<glm/ext/vector_float2.hpp>` to use these features. 849 850#### 3.3.3. GLM_EXT_vector_float3 851 852This extension exposes single-precision floating point vector with 3 components: `vec3`. 853 854Include `<glm/ext/vector_float3.hpp>` to use these features. 855 856#### 3.3.4. GLM_EXT_vector_float4 857 858This extension exposes single-precision floating point vector with 4 components: `vec4`. 859 860Include `<glm/ext/vector_float4.hpp>` to use these features. 861 862#### 3.3.5. GLM_EXT_vector_double1 863 864This extension exposes double-precision floating point vector with 1 component: `dvec1`. 865 866Include `<glm/ext/vector_double1.hpp>` to use these features. 867 868#### 3.3.6. GLM_EXT_vector_double2 869 870This extension exposes double-precision floating point vector with 2 components: `dvec2`. 871 872Include `<glm/ext/vector_double2.hpp>` to use these features. 873 874#### 3.3.7. GLM_EXT_vector_double3 875 876This extension exposes double-precision floating point vector with 3 components: `dvec3`. 877 878Include `<glm/ext/vector_double3.hpp>` to use these features. 879 880#### 3.3.8. GLM_EXT_vector_double4 881 882This extension exposes double-precision floating point vector with 4 components: `dvec4`. 883 884Include `<glm/ext/vector_double4.hpp>` to use these features. 885 886#### 3.3.9. GLM_EXT_vector_int1 887 888This extension exposes signed integer vector with 1 component: `ivec1`. 889 890Include `<glm/ext/vector_int1.hpp>` to use these features. 891 892#### 3.3.10. GLM_EXT_vector_int2 893 894This extension exposes signed integer vector with 2 components: `ivec2`. 895 896Include `<glm/ext/vector_int2.hpp>` to use these features. 897 898#### 3.3.11. GLM_EXT_vector_int3 899 900This extension exposes signed integer vector with 3 components: `ivec3`. 901 902Include `<glm/ext/vector_int3.hpp>` to use these features. 903 904#### 3.3.12. GLM_EXT_vector_int4 905 906This extension exposes signed integer vector with 4 components: `ivec4`. 907 908Include `<glm/ext/vector_int4.hpp>` to use these features. 909 910#### 3.3.13. GLM_EXT_vector_int1 911 912This extension exposes unsigned integer vector with 1 component: `uvec1`. 913 914Include `<glm/ext/vector_uint1.hpp>` to use these features. 915 916#### 3.3.14. GLM_EXT_vector_uint2 917 918This extension exposes unsigned integer vector with 2 components: `uvec2`. 919 920Include `<glm/ext/vector_uint2.hpp>` to use these features. 921 922#### 3.3.15. GLM_EXT_vector_uint3 923 924This extension exposes unsigned integer vector with 3 components: `uvec3`. 925 926Include `<glm/ext/vector_uint3.hpp>` to use these features. 927 928#### 3.3.16. GLM_EXT_vector_uint4 929 930This extension exposes unsigned integer vector with 4 components: `uvec4`. 931 932Include `<glm/ext/vector_uint4.hpp>` to use these features. 933 934#### 3.3.17. GLM_EXT_vector_bool1 935 936This extension exposes boolean vector with 1 component: `bvec1`. 937 938Include `<glm/ext/vector_bool1.hpp>` to use these features. 939 940#### 3.3.18. GLM_EXT_vector_bool2 941 942This extension exposes boolean vector with 2 components: `bvec2`. 943 944Include `<glm/ext/vector_bool2.hpp>` to use these features. 945 946#### 3.3.19. GLM_EXT_vector_bool3 947 948This extension exposes boolean vector with 3 components: `bvec3`. 949 950Include `<glm/ext/vector_bool3.hpp>` to use these features. 951 952#### 3.3.20. GLM_EXT_vector_bool4 953 954This extension exposes boolean vector with 4 components: `bvec4`. 955 956Include `<glm/ext/vector_bool4.hpp>` to use these features. 957 958### <a name="section3_4"></a> 3.4. Vector types with precision qualifiers 959 960#### 3.4.1. GLM_EXT_vector_float1_precision 961 962This extension exposes single-precision floating point vector with 1 component using various precision in term of ULPs: `lowp_vec1`, `mediump_vec1` and `highp_vec1`. 963 964Include `<glm/ext/vector_float1_precision.hpp>` to use these features. 965 966#### 3.4.2. GLM_EXT_vector_float2_precision 967 968This extension exposes single-precision floating point vector with 2 components using various precision in term of ULPs: `lowp_vec2`, `mediump_vec2` and `highp_vec2`. 969 970Include `<glm/ext/vector_float2_precision.hpp>` to use these features. 971 972#### 3.4.3. GLM_EXT_vector_float3_precision 973 974This extension exposes single-precision floating point vector with 3 components using various precision in term of ULPs: `lowp_vec3`, `mediump_vec3` and `highp_vec3`. 975 976Include `<glm/ext/vector_float3_precision.hpp>` to use these features. 977 978#### 3.4.4. GLM_EXT_vector_float4_precision 979 980This extension exposes single-precision floating point vector with 4 components using various precision in term of ULPs: `lowp_vec4`, `mediump_vec4` and `highp_vec4`. 981 982Include `<glm/ext/vector_float4_precision.hpp>` to use these features. 983 984#### 3.4.5. GLM_EXT_vector_double1_precision 985 986This extension exposes double-precision floating point vector with 1 component using various precision in term of ULPs: `lowp_dvec1`, `mediump_dvec1` and `highp_dvec1`. 987 988Include `<glm/ext/vector_double1_precision.hpp>` to use these features. 989 990#### 3.4.6. GLM_EXT_vector_double2_precision 991 992This extension exposes double-precision floating point vector with 2 components using various precision in term of ULPs: `lowp_dvec2`, `mediump_dvec2` and `highp_dvec2`. 993 994Include `<glm/ext/vector_double2_precision.hpp>` to use these features. 995 996#### 3.4.7. GLM_EXT_vector_double3_precision 997 998This extension exposes double-precision floating point vector with 3 components using various precision in term of ULPs: `lowp_dvec3`, `mediump_dvec3` and `highp_dvec3`. 999 1000Include `<glm/ext/vector_double3_precision.hpp>` to use these features. 1001 1002#### 3.4.8. GLM_EXT_vector_double4_precision 1003 1004This extension exposes double-precision floating point vector with 4 components using various precision in term of ULPs: `lowp_dvec4`, `mediump_dvec4` and `highp_dvec4`. 1005 1006Include `<glm/ext/vector_double4_precision.hpp>` to use these features. 1007 1008### <a name="section3_4"></a> 3.5. Vector functions 1009 1010#### 3.5.1. GLM_EXT_vector_common 1011 1012This extension exposes support for `min` and `max` functions taking more than two vector arguments. Also, it adds `fmin` and `fmax` variants which prevents `NaN` propagation. 1013 1014```cpp 1015#include <glm/ext/vector_float2.hpp> // vec2 1016#include <glm/ext/vector_common.hpp> // fmax 1017 1018float positiveMax(float const a, float const b) 1019{ 1020 return glm::fmax(a, b, 0.0f); 1021} 1022``` 1023 1024Include `<glm/ext/vector_common.hpp>` to use these features. 1025 1026#### 3.5.2. GLM_EXT_vector_relational 1027 1028This extension exposes `equal` and `notEqual` vector variants which takes an epsilon argument. 1029 1030```cpp 1031#include <glm/ext/vector_float2.hpp> // vec2 1032#include <glm/ext/vector_relational.hpp> // equal, all 1033 1034bool epsilonEqual(glm::vec2 const& A, glm::vec2 const& B) 1035{ 1036 float const CustomEpsilon = 0.0001f; 1037 return glm::all(glm::equal(A, B, CustomEpsilon)); 1038} 1039``` 1040 1041Include `<glm/ext/vector_relational.hpp>` to use these features. 1042 1043#### 3.5.3. GLM_EXT_vector_ulp 1044 1045This extension exposes function that measure of accuracy in numeric calculations. 1046 1047```cpp 1048#include <glm/ext/vector_ulp.hpp> 1049#include <glm/ext/vector_float4.hpp> 1050#include <glm/ext/vector_int4.hpp> 1051 1052bool test_ulp(glm::vec4 const& x) 1053{ 1054 glm::vec4 const a = glm::next_float(x); // return a float a ULP away from the float argument. 1055 return glm::all(float_distance(a, x) == glm::ivec4(1)); // check both float are a single ULP away. 1056} 1057``` 1058 1059Include `<glm/ext/vector_ulp.hpp>` to use these features. 1060 1061### <a name="section3_6"></a> 3.6. Matrix types 1062 1063#### 3.6.1. GLM_EXT_matrix_float2x2 1064 1065This extension exposes single-precision floating point vector with 2 columns by 2 rows: `mat2x2`. 1066 1067Include `<glm/ext/matrix_float2x2.hpp>` to use these features. 1068 1069#### 3.6.2. GLM_EXT_matrix_float2x3 1070 1071This extension exposes single-precision floating point vector with 2 columns by 3 rows: `mat2x3`. 1072 1073Include `<glm/ext/matrix_float2x3.hpp>` to use these features. 1074 1075#### 3.6.3. GLM_EXT_matrix_float2x4 1076 1077This extension exposes single-precision floating point vector with 2 columns by 4 rows: `mat2x4`. 1078 1079Include `<glm/ext/matrix_float2x4.hpp>` to use these features. 1080 1081#### 3.6.4. GLM_EXT_matrix_float3x2 1082 1083This extension exposes single-precision floating point vector with 3 columns by 2 rows: `mat3x2`. 1084 1085Include `<glm/ext/matrix_float3x2.hpp>` to use these features. 1086 1087#### 3.6.5. GLM_EXT_matrix_float3x3 1088 1089This extension exposes single-precision floating point vector with 3 columns by 3 rows: `mat3x3`. 1090 1091Include `<glm/ext/matrix_float3x3.hpp>` to use these features. 1092 1093#### 3.6.6. GLM_EXT_matrix_float3x4 1094 1095This extension exposes single-precision floating point vector with 3 columns by 4 rows: `mat3x4`. 1096 1097Include `<glm/ext/matrix_float3x4.hpp>` to use these features. 1098 1099#### 3.6.7. GLM_EXT_matrix_float4x2 1100 1101This extension exposes single-precision floating point vector with 4 columns by 2 rows: `mat4x2`. 1102 1103Include `<glm/ext/matrix_float4x2.hpp>` to use these features. 1104 1105#### 3.6.8. GLM_EXT_matrix_float4x3 1106 1107This extension exposes single-precision floating point vector with 4 columns by 3 rows: `mat4x3`. 1108 1109Include `<glm/ext/matrix_float4x3.hpp>` to use these features. 1110 1111#### 3.6.9. GLM_EXT_matrix_float4x4 1112 1113This extension exposes single-precision floating point vector with 4 columns by 4 rows: `mat4x4`. 1114 1115Include `<glm/ext/matrix_float4x4.hpp>` to use these features. 1116 1117#### 3.6.10. GLM_EXT_matrix_double2x2 1118 1119This extension exposes double-precision floating point vector with 2 columns by 2 rows: `dmat2x2`. 1120 1121Include `<glm/ext/matrix_double2x2.hpp>` to use these features. 1122 1123#### 3.6.11. GLM_EXT_matrix_double2x3 1124 1125This extension exposes double-precision floating point vector with 2 columns by 3 rows: `dmat2x3`. 1126 1127Include `<glm/ext/matrix_double2x3.hpp>` to use these features. 1128 1129#### 3.6.12. GLM_EXT_matrix_double2x4 1130 1131This extension exposes double-precision floating point vector with 2 columns by 4 rows: `dmat2x4`. 1132 1133Include `<glm/ext/matrix_double2x4.hpp>` to use these features. 1134 1135#### 3.6.13. GLM_EXT_matrix_double3x2 1136 1137This extension exposes double-precision floating point vector with 3 columns by 2 rows: `dmat3x2`. 1138 1139Include `<glm/ext/matrix_double3x2.hpp>` to use these features. 1140 1141#### 3.6.14. GLM_EXT_matrix_double3x3 1142 1143This extension exposes double-precision floating point vector with 3 columns by 3 rows: `dmat3x3`. 1144 1145Include `<glm/ext/matrix_double3x3.hpp>` to use these features. 1146 1147#### 3.6.15. GLM_EXT_matrix_double3x4 1148 1149This extension exposes double-precision floating point vector with 3 columns by 4 rows: `dmat3x4`. 1150 1151Include `<glm/ext/matrix_double3x4.hpp>` to use these features. 1152 1153#### 3.6.16. GLM_EXT_matrix_double4x2 1154 1155This extension exposes double-precision floating point vector with 4 columns by 2 rows: `dmat4x2`. 1156 1157Include `<glm/ext/matrix_double4x2.hpp>` to use these features. 1158 1159#### 3.6.17. GLM_EXT_matrix_double4x3 1160 1161This extension exposes double-precision floating point vector with 4 columns by 3 rows: `dmat4x3`. 1162 1163Include `<glm/ext/matrix_double4x3.hpp>` to use these features. 1164 1165#### 3.6.18. GLM_EXT_matrix_double4x4 1166 1167This extension exposes double-precision floating point vector with 4 columns by 4 rows: `dmat4x4`. 1168 1169Include `<glm/ext/matrix_double4x4.hpp>` to use these features. 1170 1171### <a name="section3_7"></a> 3.7. Matrix types with precision qualifiers 1172 1173#### 3.7.1. GLM_EXT_matrix_float2x2_precision 1174 1175This extension exposes single-precision floating point vector with 2 columns by 2 rows using various precision in term of ULPs: `lowp_mat2x2`, `mediump_mat2x2` and `highp_mat2x2`. 1176 1177Include `<glm/ext/matrix_float2x2_precision.hpp>` to use these features. 1178 1179#### 3.7.2. GLM_EXT_matrix_float2x3_precision 1180 1181This extension exposes single-precision floating point vector with 2 columns by 3 rows using various precision in term of ULPs: `lowp_mat2x3`, `mediump_mat2x3` and `highp_mat2x3`. 1182 1183Include `<glm/ext/matrix_float2x3_precision.hpp>` to use these features. 1184 1185#### 3.7.3. GLM_EXT_matrix_float2x4_precision 1186 1187This extension exposes single-precision floating point vector with 2 columns by 4 rows using various precision in term of ULPs: `lowp_mat2x4`, `mediump_mat2x4` and `highp_mat2x4`. 1188 1189Include `<glm/ext/matrix_float2x4_precision.hpp>` to use these features. 1190 1191#### 3.7.4. GLM_EXT_matrix_float3x2_precision 1192 1193This extension exposes single-precision floating point vector with 3 columns by 2 rows using various precision in term of ULPs: `lowp_mat3x2`, `mediump_mat3x2` and `highp_mat3x2`. 1194 1195Include `<glm/ext/matrix_float3x2_precision.hpp>` to use these features. 1196 1197#### 3.7.5. GLM_EXT_matrix_float3x3_precision 1198 1199This extension exposes single-precision floating point vector with 3 columns by 3 rows using various precision in term of ULPs: `lowp_mat3x3`, `mediump_mat3x3` and `highp_mat3x3`. 1200 1201Include `<glm/ext/matrix_float3x3_precision.hpp>` to use these features. 1202 1203#### 3.7.6. GLM_EXT_matrix_float3x4_precision 1204 1205This extension exposes single-precision floating point vector with 3 columns by 4 rows using various precision in term of ULPs: `lowp_mat3x4`, `mediump_mat3x4` and `highp_mat3x4`. 1206 1207Include `<glm/ext/matrix_float3x4_precision.hpp>` to use these features. 1208 1209#### 3.7.7. GLM_EXT_matrix_float4x2_precision 1210 1211This extension exposes single-precision floating point vector with 4 columns by 2 rows using various precision in term of ULPs: `lowp_mat4x2`, `mediump_mat4x2` and `highp_mat4x2`. 1212 1213Include `<glm/ext/matrix_float4x2_precision.hpp>` to use these features. 1214 1215#### 3.7.8. GLM_EXT_matrix_float4x3_precision 1216 1217This extension exposes single-precision floating point vector with 4 columns by 3 rows using various precision in term of ULPs: `lowp_mat4x3`, `mediump_mat4x3` and `highp_mat4x3`. 1218 1219Include `<glm/ext/matrix_float4x3_precision.hpp>` to use these features. 1220 1221#### 3.7.9. GLM_EXT_matrix_float4x4_precision 1222 1223This extension exposes single-precision floating point vector with 4 columns by 4 rows using various precision in term of ULPs: `lowp_mat4x4`, `mediump_mat4x4` and `highp_mat4x4`. 1224 1225Include `<glm/ext/matrix_float4x4_precision.hpp>` to use these features. 1226 1227#### 3.7.10. GLM_EXT_matrix_double2x2_precision 1228 1229This extension exposes double-precision floating point vector with 2 columns by 2 rows using various precision in term of ULPs: `lowp_dmat2x2`, `mediump_dmat2x2` and `highp_dmat2x2`. 1230 1231Include `<glm/ext/matrix_double2x2_precision.hpp>` to use these features. 1232 1233#### 3.7.11. GLM_EXT_matrix_double2x3_precision 1234 1235This extension exposes double-precision floating point vector with 2 columns by 3 rows using various precision in term of ULPs: `lowp_dmat2x3`, `mediump_dmat2x3` and `highp_dmat2x3`. 1236 1237Include `<glm/ext/matrix_double2x3_precision.hpp>` to use these features. 1238 1239#### 3.7.12. GLM_EXT_matrix_double2x4_precision 1240 1241This extension exposes double-precision floating point vector with 2 columns by 4 rows using various precision in term of ULPs: `lowp_dmat2x4`, `mediump_dmat2x4` and `highp_dmat2x4`. 1242 1243Include `<glm/ext/matrix_double2x4_precision.hpp>` to use these features. 1244 1245#### 3.7.13. GLM_EXT_matrix_double3x2_precision 1246 1247This extension exposes double-precision floating point vector with 3 columns by 2 rows using various precision in term of ULPs: `lowp_dmat3x2`, `mediump_dmat3x2` and `highp_dmat3x2`. 1248 1249Include `<glm/ext/matrix_double3x2_precision.hpp>` to use these features. 1250 1251#### 3.7.14. GLM_EXT_matrix_double3x3_precision 1252 1253This extension exposes double-precision floating point vector with 3 columns by 3 rows using various precision in term of ULPs: `lowp_dmat3x3`, `mediump_dmat3x3` and `highp_dmat3x3`. 1254 1255Include `<glm/ext/matrix_double3x3_precision.hpp>` to use these features. 1256 1257#### 3.7.15. GLM_EXT_matrix_double3x4_precision 1258 1259This extension exposes double-precision floating point vector with 3 columns by 4 rows using various precision in term of ULPs: `lowp_dmat3x4`, `mediump_dmat3x4` and `highp_dmat3x4`. 1260 1261Include `<glm/ext/matrix_double3x4_precision.hpp>` to use these features. 1262 1263#### 3.7.16. GLM_EXT_matrix_double4x2_precision 1264 1265This extension exposes double-precision floating point vector with 4 columns by 2 rows using various precision in term of ULPs: `lowp_dmat4x2`, `mediump_dmat4x2` and `highp_dmat4x2`. 1266 1267Include `<glm/ext/matrix_double4x2_precision.hpp>` to use these features. 1268 1269#### 3.7.17. GLM_EXT_matrix_double4x3_precision 1270 1271This extension exposes double-precision floating point vector with 4 columns by 3 rows using various precision in term of ULPs: `lowp_dmat4x3`, `mediump_dmat4x3` and `highp_dmat4x3`. 1272 1273Include `<glm/ext/matrix_double4x3_precision.hpp>` to use these features. 1274 1275#### 3.7.18. GLM_EXT_matrix_double4x4_precision 1276 1277This extension exposes double-precision floating point vector with 4 columns by 4 rows using various precision in term of ULPs: `lowp_dmat4x4`, `mediump_dmat4x4` and `highp_dmat4x4`. 1278 1279Include `<glm/ext/matrix_double4x4_precision.hpp>` to use these features. 1280 1281### <a name="section3_8"></a> 3.8. Matrix functions 1282 1283#### 3.8.1. GLM_EXT_matrix_relational 1284 1285This extension exposes `equal` and `notEqual` matrix variants which takes an optional epsilon argument. 1286 1287```cpp 1288#include <glm/ext/vector_bool4.hpp> // bvec4 1289#include <glm/ext/matrix_float4x4.hpp> // mat4 1290#include <glm/ext/matrix_relational.hpp> // equal, all 1291 1292bool epsilonEqual(glm::mat4 const& A, glm::mat4 const& B) 1293{ 1294 float const CustomEpsilon = 0.0001f; 1295 glm::bvec4 const ColumnEqual = glm::equal(A, B, CustomEpsilon); // Evaluation per column 1296 return glm::all(ColumnEqual); 1297} 1298``` 1299 1300Include `<glm/ext/matrix_relational.hpp>` to use these features. 1301 1302#### 3.8.2. GLM_EXT_matrix_transform 1303 1304This extension exposes matrix transformation functions: `translate`, `rotate` and `scale`. 1305 1306```cpp 1307#include <glm/ext/vector_float2.hpp> // vec2 1308#include <glm/ext/vector_float3.hpp> // vec3 1309#include <glm/ext/matrix_float4x4.hpp> // mat4x4 1310#include <glm/ext/matrix_transform.hpp> // translate, rotate, scale, identity 1311 1312glm::mat4 computeModelViewMatrix(float Translate, glm::vec2 const & Rotate) 1313{ 1314 glm::mat4 View = glm::translate(glm::identity(), glm::vec3(0.0f, 0.0f, -Translate)); 1315 View = glm::rotate(View, Rotate.y, glm::vec3(-1.0f, 0.0f, 0.0f)); 1316 View = glm::rotate(View, Rotate.x, glm::vec3(0.0f, 1.0f, 0.0f)); 1317 glm::mat4 Model = glm::scale(glm::identity(), glm::vec3(0.5f)); 1318 return View * Model; 1319} 1320``` 1321 1322Include `<glm/ext/matrix_transform.hpp>` to use these features. 1323 1324#### 3.8.3. GLM_EXT_matrix_clip_space 1325 1326This extension exposes functions to transform scenes into the clip space. 1327 1328```cpp 1329#include <glm/ext/matrix_float4x4.hpp> // mat4x4 1330#include <glm/ext/matrix_clip_space.hpp> // perspective 1331#include <glm/trigonometric.hpp> // radians 1332 1333glm::mat4 computeProjection(float Width, float Height) 1334{ 1335 return glm::perspective(glm::radians(45.0f), Width / Height, 0.1f, 100.f); 1336} 1337``` 1338 1339Include `<glm/ext/matrix_clip_space.hpp>` to use these features. 1340 1341#### 3.8.4. GLM_EXT_matrix_projection 1342 1343This extension exposes functions to map object coordinates into window coordinates and reverse 1344 1345Include `<glm/ext/matrix_projection.hpp>` to use these features. 1346 1347### <a name="section3_9"></a> 3.9. Quaternion types 1348 1349#### 3.9.1. GLM_EXT_quaternion_float 1350 1351This extension exposes single-precision floating point quaternion: `quat`. 1352 1353Include `<glm/ext/quaternion_float.hpp>` to use these features. 1354 1355#### 3.9.2. GLM_EXT_quaternion_double 1356 1357This extension exposes double-precision floating point quaternion: `dquat`. 1358 1359Include `<glm/ext/quaternion_double.hpp>` to use these features. 1360 1361### <a name="section3_10"></a> 3.10. Quaternion types with precision qualifiers 1362 1363#### 3.10.1. GLM_EXT_quaternion_float_precision 1364 1365This extension exposes single-precision floating point quaternion using various precision in term of ULPs: `lowp_quat`, `mediump_quat` and `highp_quat`. 1366 1367Include `<glm/ext/quaternion_float_precision.hpp>` to use these features. 1368 1369#### 3.10.2. GLM_EXT_quaternion_double_precision 1370 1371This extension exposes double-precision floating point quaternion using various precision in term of ULPs: `lowp_dquat`, `mediump_dquat` and `highp_dquat`. 1372 1373Include `<glm/ext/quaternion_double_precision.hpp>` to use these features. 1374 1375### <a name="section3_11"></a> 3.11. Quaternion functions 1376 1377#### 3.11.1. GLM_EXT_quaternion_common 1378 1379This extension exposes common quaternion functions such as `slerp`, `conjugate` and `inverse`. 1380 1381Include `<glm/ext/quaternion_common.hpp>` to use these features. 1382 1383#### 3.11.2. GLM_EXT_quaternion_geometric 1384 1385This extension exposes geometric quaternion functions such as `length`, `normalize`, `dot` and `cross`. 1386 1387Include `<glm/ext/quaternion_geometric.hpp>` to use these features. 1388 1389#### 3.11.3. GLM_EXT_quaternion_trigonometric 1390 1391This extension exposes trigonometric quaternion functions such as `angle` and `axis`. 1392 1393Include `<glm/ext/quaternion_trigonometric.hpp>` to use these features. 1394 1395#### 3.11.4. GLM_EXT_quaternion_exponential 1396 1397This extensions expose exponential functions for quaternions such as `exp`, `log`, `pow` and `sqrt`. 1398 1399Include `<glm/ext/quaternion_exponential.hpp>` to use these features. 1400 1401#### 3.11.5. GLM_EXT_quaternion_relational 1402 1403This extension exposes relational functions to compare quaternions. 1404 1405Include `<glm/ext/quaternion_relational.hpp>` to use these features. 1406 1407#### 3.11.6. GLM_EXT_quaternion_transform 1408 1409This extension exposes functions to transform objects. 1410 1411Include `<glm/ext/quaternion_transform.hpp>` to use these features. 1412 1413--- 1414<div style="page-break-after: always;"> </div> 1415 1416## <a name="section4"></a> 4. Recommended extensions 1417 1418GLM extends the core GLSL feature set with extensions. These extensions include: quaternion, transformation, spline, matrix inverse, color spaces, etc. 1419 1420To include an extension, we only need to include the dedicated header file. Once included, the features are added to the GLM namespace. 1421 1422```cpp 1423#include <glm/glm.hpp> 1424#include <glm/gtc/matrix_transform.hpp> 1425 1426int foo() 1427{ 1428 glm::vec4 Position = glm::vec4(glm:: vec3(0.0f), 1.0f); 1429 glm::mat4 Model = glm::translate(glm::mat4(1.0f), glm::vec3(1.0f)); 1430 1431 glm::vec4 Transformed = Model * Position; 1432 ... 1433 1434 return 0; 1435} 1436``` 1437 1438When an extension is included, all the dependent core functionalities and extensions will be included as well. 1439 1440### <a name="section4_1"></a> 4.1. GLM_GTC_bitfield 1441 1442Fast bitfield operations on scalar and vector variables. 1443 1444`<glm/gtc/bitfield.hpp>` need to be included to use these features. 1445 1446### <a name="section4_2"></a> 4.2. GLM_GTC_color_space 1447 1448Conversion between linear RGB and sRGB color spaces. 1449 1450`<glm/gtc/color_space.hpp>` need to be included to use these features. 1451 1452### <a name="section4_3"></a> 4.3. GLM_GTC_constants 1453 1454Provide a list of built-in constants. 1455 1456`<glm/gtc/constants.hpp>` need to be included to use these features. 1457 1458### <a name="section4_4"></a> 4.4. GLM\_GTC\_epsilon 1459 1460Approximate equality comparisons for floating-point numbers, possibly with a user-defined epsilon. 1461 1462`<glm/gtc/epsilon.hpp>` need to be included to use these features. 1463 1464### <a name="section4_5"></a> 4.5. GLM\_GTC\_integer 1465 1466Integer variants of core GLM functions. 1467 1468`<glm/gtc/integer.hpp>` need to be included to use these features. 1469 1470### <a name="section4_6"></a> 4.6. GLM\_GTC\_matrix\_access 1471 1472Functions to conveniently access the individual rows or columns of a matrix. 1473 1474`<glm/gtc/matrix_access.hpp>` need to be included to use these features. 1475 1476### <a name="section4_7"></a> 4.7. GLM\_GTC\_matrix\_integer 1477 1478Integer matrix types similar to the core floating-point matrices. Some operations (such as inverse and determinant) are not supported. 1479 1480`<glm/gtc/matrix_integer.hpp>` need to be included to use these features. 1481 1482### <a name="section4_8"></a> 4.8. GLM\_GTC\_matrix\_inverse 1483 1484Additional matrix inverse functions. 1485 1486`<glm/gtc/matrix_inverse.hpp>` need to be included to use these features. 1487 1488### <a name="section4_9"></a> 4.9. GLM\_GTC\_matrix\_transform 1489 1490Matrix transformation functions that follow the OpenGL fixed-function conventions. 1491 1492For example, the `lookAt` function generates a transformation matrix that projects world coordinates into eye coordinates suitable for projection matrices (e.g. `perspective`, `ortho`). See the OpenGL compatibility specifications for more information about the layout of these generated matrices. 1493 1494The 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 1495projective matrix functions (`perspective`, `ortho`, etc) are designed to expect. The OpenGL compatibility specifications define the particular layout of this eye space. 1496 1497`<glm/gtc/matrix_transform.hpp>` need to be included to use these features. 1498 1499### <a name="section4_10"></a> 4.10. GLM\_GTC\_noise 1500 1501Define 2D, 3D and 4D procedural noise functions. 1502 1503<`glm/gtc/noise.hpp>` need to be included to use these features. 1504 1505![](/doc/manual/noise-simplex1.jpg) 1506 1507Figure 4.10.1: glm::simplex(glm::vec2(x / 16.f, y / 16.f)); 1508 1509![](/doc/manual/noise-simplex2.jpg) 1510 1511Figure 4.10.2: glm::simplex(glm::vec3(x / 16.f, y / 16.f, 0.5f)); 1512 1513![](/doc/manual/noise-simplex3.jpg) 1514 1515Figure 4.10.3: glm::simplex(glm::vec4(x / 16.f, y / 16.f, 0.5f, 0.5f)); 1516 1517![](/doc/manual/noise-perlin1.jpg) 1518 1519Figure 4.10.4: glm::perlin(glm::vec2(x / 16.f, y / 16.f)); 1520 1521![](/doc/manual/noise-perlin2.jpg) 1522 1523Figure 4.10.5: glm::perlin(glm::vec3(x / 16.f, y / 16.f, 0.5f)); 1524 1525![](/doc/manual/noise-perlin3.jpg) 1526 1527Figure 4.10.6: glm::perlin(glm::vec4(x / 16.f, y / 16.f, 0.5f, 0.5f))); 1528 1529![](/doc/manual/noise-perlin4.png) 1530 1531Figure 4.10.7: glm::perlin(glm::vec2(x / 16.f, y / 16.f), glm::vec2(2.0f)); 1532 1533![](/doc/manual/noise-perlin5.png) 1534 1535Figure 4.10.8: glm::perlin(glm::vec3(x / 16.f, y / 16.f, 0.5f), glm::vec3(2.0f)); 1536 1537![](/doc/manual/noise-perlin6.png) 1538 1539Figure 4.10.9: glm::perlin(glm::vec4(x / 16.f, y / 16.f, glm::vec2(0.5f)), glm::vec4(2.0f)); 1540 1541### <a name="section4_11"></a> 4.11. GLM\_GTC\_packing 1542 1543Convert 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. 1544 1545`<glm/gtc/packing.hpp>` need to be included to use these features. 1546 1547### <a name="section4_12"></a> 4.12. GLM\_GTC\_quaternion 1548 1549Quaternions and operations upon thereof. 1550 1551`<glm/gtc/quaternion.hpp>` need to be included to use these features. 1552 1553### <a name="section4_13"></a> 4.13. GLM\_GTC\_random 1554 1555Probability distributions in up to four dimensions. 1556 1557`<glm/gtc/random.hpp>` need to be included to use these features. 1558 1559![](/doc/manual/random-linearrand.png) 1560 1561Figure 4.13.1: glm::vec4(glm::linearRand(glm::vec2(-1), glm::vec2(1)), 0, 1); 1562 1563![](/doc/manual/random-circularrand.png) 1564 1565Figure 4.13.2: glm::vec4(glm::circularRand(1.0f), 0, 1); 1566 1567![](/doc/manual/random-sphericalrand.png) 1568 1569Figure 4.13.3: glm::vec4(glm::sphericalRand(1.0f), 1); 1570 1571![](/doc/manual/random-diskrand.png) 1572 1573Figure 4.13.4: glm::vec4(glm::diskRand(1.0f), 0, 1); 1574 1575![](/doc/manual/random-ballrand.png) 1576 1577Figure 4.13.5: glm::vec4(glm::ballRand(1.0f), 1); 1578 1579![](/doc/manual/random-gaussrand.png) 1580 1581Figure 4.13.6: glm::vec4(glm::gaussRand(glm::vec3(0), glm::vec3(1)), 1); 1582 1583### <a name="section4_14"></a> 4.14. GLM\_GTC\_reciprocal 1584 1585Reciprocal trigonometric functions (e.g. secant, cosecant, tangent). 1586 1587`<glm/gtc/reciprocal.hpp>` need to be included to use the features of this extension. 1588 1589### <a name="section4_15"></a> 4.15. GLM\_GTC\_round 1590 1591Various rounding operations and common special cases thereof. 1592 1593`<glm/gtc/round.hpp>` need to be included to use the features of this extension. 1594 1595### <a name="section4_16"></a> 4.16. GLM\_GTC\_type\_aligned 1596 1597Aligned vector types. 1598 1599`<glm/gtc/type_aligned.hpp>` need to be included to use the features of this extension. 1600 1601### <a name="section4_17"></a> 4.17. GLM\_GTC\_type\_precision 1602 1603Vector and matrix types with defined precisions, e.g. `i8vec4`, which is a 4D vector of signed 8-bit integers. 1604 1605`<glm/gtc/type\_precision.hpp>` need to be included to use the features of this extension. 1606 1607### <a name="section4_18"></a> 4.18. GLM\_GTC\_type\_ptr 1608 1609Facilitate interactions between pointers to basic types (e.g. `float*`) and GLM types (e.g. `mat4`). 1610 1611This extension defines an overloaded function, `glm::value_ptr`, which returns a pointer to the memory layout of any GLM vector or matrix (`vec3`, `mat4`, etc.). Matrix types store their values in column-major order. This is useful for uploading data to matrices or for copying data to buffer objects. 1612 1613```cpp 1614// GLM_GTC_type_ptr provides a safe solution: 1615#include <glm/glm.hpp> 1616#include <glm/gtc/type_ptr.hpp> 1617 1618void foo() 1619{ 1620 glm::vec4 v(0.0f); 1621 glm::mat4 m(1.0f); 1622 ... 1623 glVertex3fv(glm::value_ptr(v)) 1624 glLoadMatrixfv(glm::value_ptr(m)); 1625} 1626 1627// Another solution, this one inspired by the STL: 1628#include <glm/glm.hpp> 1629 1630void foo() 1631{ 1632 glm::vec4 v(0.0f); 1633 glm::mat4 m(1.0f); 1634 ... 1635 glVertex3fv(&v[0]); 1636 glLoadMatrixfv(&m[0][0]); 1637} 1638``` 1639 1640*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 1641implicit cast in this example. However cast operators may produce programs running with unexpected behaviours without build error or any form of notification. * 1642 1643`<glm/gtc/type_ptr.hpp>` need to be included to use these features. 1644 1645### <a name="section4_19"></a> 4.19. GLM\_GTC\_ulp 1646 1647Measure 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). 1648 1649`<glm/gtc/ulp.hpp>` need to be included to use these features. 1650 1651### <a name="section4_20"></a> 4.20. GLM\_GTC\_vec1 1652 1653Add \*vec1 types. 1654 1655`<glm/gtc/vec1.hpp>` need to be included to use these features. 1656 1657--- 1658<div style="page-break-after: always;"> </div> 1659 1660## <a name="section5"></a> 5. OpenGL interoperability 1661 1662### <a name="section5_1"></a> 5.1. GLM replacements for deprecated OpenGL functions 1663 1664OpenGL 3.1 specification has deprecated some features that have been removed from OpenGL 3.2 core profile specification. GLM provides some replacement functions. 1665 1666[***glRotate{f, d}:***](https://www.opengl.org/sdk/docs/man2/xhtml/glRotate.xml) 1667 1668```cpp 1669glm::mat4 glm::rotate(glm::mat4 const& m, float angle, glm::vec3 const& axis); 1670glm::dmat4 glm::rotate(glm::dmat4 const& m, double angle, glm::dvec3 const& axis); 1671``` 1672 1673From `GLM_GTC_matrix_transform` extension: <glm/gtc/matrix\_transform.hpp> 1674 1675[***glScale{f, d}:***](http://www.opengl.org/sdk/docs/man2/xhtml/glScale.xml) 1676 1677```cpp 1678glm::mat4 glm::scale(glm::mat4 const& m, glm::vec3 const& factors); 1679glm::dmat4 glm::scale(glm::dmat4 const& m, glm::dvec3 const& factors); 1680``` 1681 1682From `GLM_GTC_matrix_transform` extension: <glm/gtc/matrix\_transform.hpp> 1683 1684[***glTranslate{f, d}:***](https://www.opengl.org/sdk/docs/man2/xhtml/glTranslate.xml) 1685 1686```cpp 1687glm::mat4 glm::translate(glm::mat4 const& m, glm::vec3 const& translation); 1688glm::dmat4 glm::translate(glm::dmat4 const& m, glm::dvec3 const& translation); 1689``` 1690 1691From `GLM_GTC_matrix_transform` extension: <glm/gtc/matrix\_transform.hpp> 1692 1693[***glLoadIdentity:***](https://www.opengl.org/sdk/docs/man2/xhtml/glLoadIdentity.xml) 1694 1695```cpp 1696glm::mat4(1.0) or glm::mat4(); 1697glm::dmat4(1.0) or glm::dmat4(); 1698``` 1699 1700From GLM core library: `<glm/glm.hpp>` 1701 1702[***glMultMatrix{f, d}:***](https://www.opengl.org/sdk/docs/man2/xhtml/glMultMatrix.xml) 1703 1704```cpp 1705glm::mat4() * glm::mat4(); 1706glm::dmat4() * glm::dmat4(); 1707``` 1708 1709From GLM core library: `<glm/glm.hpp>` 1710 1711[***glLoadTransposeMatrix{f, d}:***](https://www.opengl.org/sdk/docs/man2/xhtml/glLoadTransposeMatrix.xml) 1712 1713```cpp 1714glm::transpose(glm::mat4()); 1715glm::transpose(glm::dmat4()); 1716``` 1717 1718From GLM core library: `<glm/glm.hpp>` 1719 1720[***glMultTransposeMatrix{f, d}:***](https://www.opengl.org/sdk/docs/man2/xhtml/glMultTransposeMatrix.xml) 1721 1722```cpp 1723glm::mat4() * glm::transpose(glm::mat4()); 1724glm::dmat4() * glm::transpose(glm::dmat4()); 1725``` 1726 1727From GLM core library: `<glm/glm.hpp>` 1728 1729[***glFrustum:***](http://www.opengl.org/sdk/docs/man2/xhtml/glFrustum.xml) 1730 1731```cpp 1732glm::mat4 glm::frustum(float left, float right, float bottom, float top, float zNear, float zFar); 1733glm::dmat4 glm::frustum(double left, double right, double bottom, double top, double zNear, double zFar); 1734``` 1735 1736From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1737 1738[***glOrtho:***](https://www.opengl.org/sdk/docs/man2/xhtml/glOrtho.xml) 1739 1740```cpp 1741glm::mat4 glm::ortho(float left, float right, float bottom, float top, float zNear, float zFar); 1742glm::dmat4 glm::ortho(double left, double right, double bottom, double top, double zNear, double zFar); 1743``` 1744 1745From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1746 1747### <a name="section5_2"></a> 5.2. GLM replacements for GLU functions 1748 1749[***gluLookAt:***](https://www.opengl.org/sdk/docs/man2/xhtml/gluLookAt.xml) 1750 1751```cpp 1752glm::mat4 glm::lookAt(glm::vec3 const& eye, glm::vec3 const& center, glm::vec3 const& up); 1753glm::dmat4 glm::lookAt(glm::dvec3 const& eye, glm::dvec3 const& center, glm::dvec3 const& up); 1754``` 1755 1756From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1757 1758[***gluOrtho2D:***](https://www.opengl.org/sdk/docs/man2/xhtml/gluOrtho2D.xml) 1759 1760```cpp 1761glm::mat4 glm::ortho(float left, float right, float bottom, float top); 1762glm::dmat4 glm::ortho(double left, double right, double bottom, double top); 1763``` 1764 1765From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1766 1767[***gluPerspective:***](https://www.opengl.org/sdk/docs/man2/xhtml/gluPerspective.xml) 1768 1769```cpp 1770glm::mat4 perspective(float fovy, float aspect, float zNear, float zFar); 1771glm::dmat4 perspective(double fovy, double aspect, double zNear, double zFar); 1772``` 1773 1774Note that in GLM, fovy is expressed in radians, not degrees. 1775 1776From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1777 1778[***gluPickMatrix:***](https://www.opengl.org/sdk/docs/man2/xhtml/gluPickMatrix.xml) 1779 1780```cpp 1781glm::mat4 pickMatrix(glm::vec2 const& center, glm::vec2 const& delta, glm::ivec4 const& viewport); 1782glm::dmat4 pickMatrix(glm::dvec2 const& center, glm::dvec2 const& delta, glm::ivec4 const& viewport); 1783``` 1784 1785From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1786 1787[***gluProject:***](http://www.opengl.org/sdk/docs/man2/xhtml/gluProject.xml) 1788 1789```cpp 1790glm::vec3 project(glm::vec3 const& obj, glm::mat4 const& model, glm::mat4 const& proj, glm::ivec4 const& viewport); 1791glm::dvec3 project(glm::dvec3 const& obj, glm::dmat4 const& model, glm::dmat4 const& proj, glm::ivec4 const& viewport); 1792``` 1793 1794From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1795 1796[***gluUnProject:***](https://www.opengl.org/sdk/docs/man2/xhtml/gluUnProject.xml) 1797 1798```cpp 1799glm::vec3 unProject(glm::vec3 const& win, glm::mat4 const& model, glm::mat4 const& proj, glm::ivec4 const& viewport); 1800glm::dvec3 unProject(glm::dvec3 const& win, glm::dmat4 const& model, glm::dmat4 const& proj, glm::ivec4 const& viewport); 1801``` 1802 1803From `GLM_GTC_matrix_transform` extension: `<glm/gtc/matrix_transform.hpp>` 1804 1805--- 1806<div style="page-break-after: always;"> </div> 1807 1808## <a name="section6"></a> 6. Known issues 1809 1810This section reports GLSL features that GLM can't accurately emulate due to language restrictions. 1811 1812### <a name="section6_1"></a> 6.1. not function 1813 1814The 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. 1815 1816### <a name="section6_2"></a> 6.2. Precision qualifiers support 1817 1818GLM supports GLSL precision qualifiers through prefixes instead of qualifiers. For example, GLM exposes \verb|lowp_vec4|, \verb|mediump_vec4| and \verb|highp_vec4| as variations of \verb|vec4|. 1819 1820Similarly to GLSL, GLM precision qualifiers are used to trade precision of operations in term of [ULPs](http://en.wikipedia.org/wiki/Unit_in_the_last_place) for better performance. By default, all the types use high precision. 1821 1822```cpp 1823// Using precision qualifier in GLSL: 1824 1825ivec3 foo(in vec4 v) 1826{ 1827 highp vec4 a = v; 1828 mediump vec4 b = a; 1829 lowp ivec3 c = ivec3(b); 1830 return c; 1831} 1832 1833// Using precision qualifier in GLM: 1834 1835#include <glm/glm.hpp> 1836 1837ivec3 foo(const vec4 & v) 1838{ 1839 highp_vec4 a = v; 1840 medium_vec4 b = a; 1841 lowp_ivec3 c = glm::ivec3(b); 1842 return c; 1843} 1844``` 1845 1846--- 1847<div style="page-break-after: always;"> </div> 1848 1849## <a name="section7"></a> 7. FAQ 1850 1851### <a name="section7_1"></a> 7.1 Why GLM follows GLSL specification and conventions? 1852 1853Following GLSL conventions is a really strict policy of GLM. It has been designed following the idea that everyone does its own math library with his own conventions. The idea is that brilliant developers (the OpenGL ARB) worked together and agreed to make GLSL. Following GLSL conventions 1854is a way to find consensus. Moreover, basically when a developer knows GLSL, he knows GLM. 1855 1856### <a name="section7_2"></a> 7.2. Does GLM run GLSL program? 1857 1858No, GLM is a C++ implementation of a subset of GLSL. 1859 1860### <a name="section7_3"></a> 7.3. Does a GLSL compiler build GLM codes? 1861 1862No, this is not what GLM attends to do. 1863 1864### <a name="section7_4"></a> 7.4. Should I use ‘GTX’ extensions? 1865 1866GTX extensions are qualified to be experimental extensions. In GLM this means that these extensions might change from version to version without any restriction. In practice, it doesn’t really change except time to 1867time. GTC extensions are stabled, tested and perfectly reliable in time. Many GTX extensions extend GTC extensions and provide a way to explore features and implementations and APIs and then are promoted to GTC 1868extensions. This is fairly the way OpenGL features are developed; through extensions. 1869 1870Stating with GLM 0.9.9, to use experimental extensions, an application must define GLM_ENABLE_EXPERIMENTAL. 1871 1872### <a name="section7_5"></a> 7.5. Where can I ask my questions? 1873 1874A good place is [stackoverflow](http://stackoverflow.com/search?q=GLM) using the GLM tag. 1875 1876### <a name="section7_6"></a> 7.6. Where can I find the documentation of extensions? 1877 1878The Doxygen generated documentation includes a complete list of all extensions available. Explore this [*API documentation*](http://glm.g-truc.net/html/index.html) to get a complete 1879view of all GLM capabilities! 1880 1881### <a name="section7_7"></a> 7.7. Should I use ‘using namespace glm;’? 1882 1883NO! Chances are that if using namespace glm; is called, especially in a header file, name collisions will happen as GLM is based on GLSL which uses common tokens for types and functions. Avoiding using namespace 1884glm; will a higher compatibility with third party library and SDKs. 1885 1886### <a name="section7_8"></a> 7.8. Is GLM fast? 1887 1888GLM is mainly designed to be convenient and that's why it is written against the GLSL specification. 1889 1890Following the Pareto principle where 20% of the code consumes 80% of the execution time, GLM operates perfectly on the 80% of the code that consumes 20% of the performances. Furthermore, thanks to the lowp, 1891mediump and highp qualifiers, GLM provides approximations which trade precision for performance. Finally, GLM can automatically produce SIMD optimized code for functions of its implementation. 1892 1893However, on performance critical code paths, we should expect that dedicated algorithms should be written to reach peak performance. 1894 1895### <a name="section7_9"></a> 7.9. When I build with Visual C++ with /W4 warning level, I have warnings... 1896 1897You 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 1898(`/Za`) which generates warnings when used. If these extensions are enabled, then GLM will take advantage of them and the compiler will generate warnings. 1899 1900### <a name="section7_10"></a> 7.10. Why some GLM functions can crash because of division by zero? 1901 1902GLM functions crashing is the result of a domain error. Such behavior follows the precedent set by C and C++'s standard library. For example, it’s a domain error to pass a null vector (all zeroes) to glm::normalize function, or to pass a negative number into std::sqrt. 1903 1904### <a name="section7_11"></a> 7.11. What unit for angles is used in GLM? 1905 1906GLSL is using radians but GLU is using degrees to express angles. This has caused GLM to use inconsistent units for angles. Starting with GLM 0.9.6, all GLM functions are using radians. For more information, follow 1907the [link](http://www.g-truc.net/post-0693.html#menu). 1908 1909### <a name="section7_12"></a> 7.12. Windows headers cause build errors... 1910 1911Some Windows headers define min and max as macros which may cause compatibility with third party libraries such as GLM. 1912It 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. 1913To workaround the incompatibility with these macros, GLM will systematically undef these macros if they are defined. 1914 1915### <a name="section7_13"></a> 7.13. Constant expressions support 1916 1917GLM has some C++ <a href="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. 1918Unfortunately, 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. 1919 1920--- 1921<div style="page-break-after: always;"> </div> 1922 1923## <a name="section8"></a> 8. Code samples 1924 1925This series of samples only shows various GLM features without consideration of any sort. 1926 1927### <a name="section8_1"></a> 8.1. Compute a triangle normal 1928 1929```cpp 1930#include <glm/glm.hpp> // vec3 normalize cross 1931 1932glm::vec3 computeNormal(glm::vec3 const& a, glm::vec3 const& b, glm::vec3 const& c) 1933{ 1934 return glm::normalize(glm::cross(c - a, b - a)); 1935} 1936 1937// A much faster but less accurate alternative: 1938#include <glm/glm.hpp> // vec3 cross 1939#include <glm/gtx/fast_square_root.hpp> // fastNormalize 1940 1941glm::vec3 computeNormal(glm::vec3 const& a, glm::vec3 const& b, glm::vec3 const& c) 1942{ 1943 return glm::fastNormalize(glm::cross(c - a, b - a)); 1944} 1945``` 1946 1947### <a name="section8_2"></a> 8.2. Matrix transform 1948 1949```cpp 1950#include <glm/glm.hpp> // vec3, vec4, ivec4, mat4 1951#include <glm/gtc/matrix_transform.hpp> // translate, rotate, scale, perspective 1952#include <glm/gtc/type_ptr.hpp> // value_ptr 1953 1954void setUniformMVP(GLuint Location, glm::vec3 const& Translate, glm::vec3 const& Rotate) 1955{ 1956 glm::mat4 Projection = glm::perspective(45.0f, 4.0f / 3.0f, 0.1f, 100.f); 1957 glm::mat4 ViewTranslate = glm::translate( 1958 glm::mat4(1.0f), Translate); 1959 glm::mat4 ViewRotateX = glm::rotate( 1960 ViewTranslate, Rotate.y, glm::vec3(-1.0f, 0.0f, 0.0f)); 1961 glm::mat4 View = glm::rotate(ViewRotateX, 1962 Rotate.x, glm::vec3(0.0f, 1.0f, 0.0f)); 1963 glm::mat4 Model = glm::scale( 1964 glm::mat4(1.0f), glm::vec3(0.5f)); 1965 glm::mat4 MVP = Projection * View * Model; 1966 glUniformMatrix4fv(Location, 1, GL_FALSE, glm::value_ptr(MVP)); 1967} 1968``` 1969 1970### <a name="section8_3"></a> 8.3. Vector types 1971 1972```cpp 1973#include <glm/glm.hpp> // vec2 1974#include <glm/gtc/type_precision.hpp> // hvec2, i8vec2, i32vec2 1975 1976std::size_t const VertexCount = 4; 1977 1978// Float quad geometry 1979std::size_t const PositionSizeF32 = VertexCount * sizeof(glm::vec2); 1980glm::vec2 const PositionDataF32[VertexCount] = 1981{ 1982 glm::vec2(-1.0f,-1.0f), 1983 glm::vec2( 1.0f,-1.0f), 1984 glm::vec2( 1.0f, 1.0f), 1985 glm::vec2(-1.0f, 1.0f) 1986}; 1987 1988// Half-float quad geometry 1989std::size_t const PositionSizeF16 = VertexCount * sizeof(glm::hvec2); 1990glm::hvec2 const PositionDataF16[VertexCount] = 1991{ 1992 glm::hvec2(-1.0f, -1.0f), 1993 glm::hvec2( 1.0f, -1.0f), 1994 glm::hvec2( 1.0f, 1.0f), 1995 glm::hvec2(-1.0f, 1.0f) 1996}; 1997 1998// 8 bits signed integer quad geometry 1999std::size_t const PositionSizeI8 = VertexCount * sizeof(glm::i8vec2); 2000glm::i8vec2 const PositionDataI8[VertexCount] = 2001{ 2002 glm::i8vec2(-1,-1), 2003 glm::i8vec2( 1,-1), 2004 glm::i8vec2( 1, 1), 2005 glm::i8vec2(-1, 1) 2006}; 2007 2008// 32 bits signed integer quad geometry 2009std::size_t const PositionSizeI32 = VertexCount * sizeof(glm::i32vec2); 2010glm::i32vec2 const PositionDataI32[VertexCount] = 2011{ 2012 glm::i32vec2(-1,-1), 2013 glm::i32vec2( 1,-1), 2014 glm::i32vec2( 1, 1), 2015 glm::i32vec2(-1, 1) 2016}; 2017``` 2018 2019### <a name="section8_4"></a> 8.4. Lighting 2020 2021```cpp 2022#include <glm/glm.hpp> // vec3 normalize reflect dot pow 2023#include <glm/gtc/random.hpp> // ballRand 2024 2025// vecRand3, generate a random and equiprobable normalized vec3 2026glm::vec3 lighting(intersection const& Intersection, material const& Material, light const& Light, glm::vec3 const& View) 2027{ 2028 glm::vec3 Color = glm::vec3(0.0f); 2029 glm::vec3 LightVertor = glm::normalize( 2030 Light.position() - Intersection.globalPosition() + 2031 glm::ballRand(0.0f, Light.inaccuracy()); 2032 2033 if(!shadow(Intersection.globalPosition(), Light.position(), LightVertor)) 2034 { 2035 float Diffuse = glm::dot(Intersection.normal(), LightVector); 2036 if(Diffuse <= 0.0f) 2037 return Color; 2038 2039 if(Material.isDiffuse()) 2040 Color += Light.color() * Material.diffuse() * Diffuse; 2041 2042 if(Material.isSpecular()) 2043 { 2044 glm::vec3 Reflect = glm::reflect(-LightVector, Intersection.normal()); 2045 float Dot = glm::dot(Reflect, View); 2046 float Base = Dot > 0.0f ? Dot : 0.0f; 2047 float Specular = glm::pow(Base, Material.exponent()); 2048 Color += Material.specular() \* Specular; 2049 } 2050 } 2051 2052 return Color; 2053} 2054``` 2055 2056--- 2057<div style="page-break-after: always;"> </div> 2058 2059## <a name="section9"></a> 9. Contributing to GLM 2060 2061### <a name="section9_1"></a> 9.1. Submitting bug reports 2062 2063Bug should be reported on Github using the [issue page](https://github.com/g-truc/glm/issues). 2064 2065A minimal code to reproduce the issue will help. 2066 2067Additional, bugs can be configuration specific. We can report the configuration by defining `GLM_FORCE_MESSAGES` before including GLM headers then build and copy paste the build messages GLM will output. 2068 2069```cpp 2070#define GLM_FORCE_MESSAGES 2071#include <glm/glm.hpp> 2072``` 2073 2074An example of build messages generated by GLM: 2075``` 2076GLM: 0.9.9.1 2077GLM: C++ 17 with extensions 2078GLM: GCC compiler detected" 2079GLM: x86 64 bits with AVX instruction set build target 2080GLM: Linux platform detected 2081GLM: GLM_FORCE_SWIZZLE is undefined. swizzling functions or operators are disabled. 2082GLM: GLM_FORCE_SIZE_T_LENGTH is undefined. .length() returns a glm::length_t, a typedef of int following GLSL. 2083GLM: GLM_FORCE_UNRESTRICTED_GENTYPE is undefined. Follows strictly GLSL on valid function genTypes. 2084GLM: GLM_FORCE_DEPTH_ZERO_TO_ONE is undefined. Using negative one to one depth clip space. 2085GLM: GLM_FORCE_LEFT_HANDED is undefined. Using right handed coordinate system. 2086``` 2087 2088### <a name="section9_2"></a> 9.2. Contributing to GLM with pull request 2089 2090This tutorial will show us how to successfully contribute a bug-fix to GLM using GitHub's Pull Request workflow. 2091 2092We will be typing git commands in the Terminal. Mac and Linux users may have git pre-installed. You can download git from [here](http://git-scm.com/downloads). 2093 2094The tutorial assumes you have some basic understanding of git concepts - repositories, branches, commits, etc. Explaining it all from scratch is beyond the scope of this tutorial. Some good links to learn git basics are: [Link 1](http://git-scm.com/book/en/Getting-Started-Git-Basics), [Link 2](https://www.atlassian.com/git/tutorial/git-basics) 2095 2096#### Step 1: Setup our GLM Fork 2097 2098We will make our changes in our own copy of the GLM sitory. On the GLM GitHub repo and we press the Fork button. 2099We need to download a copy of our fork to our local machine. In the terminal, type: 2100 2101``` 2102>>> git clone <our-repository-fork-git-url> 2103``` 2104 2105This will clone our fork repository into the current folder. 2106 2107We can find our repository git url on the Github reposotory page. The url looks like this: `https://github.com/<our-username>/<repository-name>.git` 2108 2109#### Step 2: Synchronizing our fork 2110 2111We can use the following command to add `upstream` (original project repository) as a remote repository so that we can fetch the latest GLM commits into our branch and keep our forked copy is synchronized. 2112 2113``` 2114>>> git remote add upstream https://github.com/processing/processing.git 2115``` 2116 2117To synchronize our fork to the latest commit in the GLM repository, we can use the following command: 2118 2119``` 2120>>> git fetch upstream 2121``` 2122 2123Then, we can merge the remote master branch to our current branch: 2124 2125``` 2126>>> git merge upstream/master 2127``` 2128 2129Now our local copy of our fork has been synchronized. However, the fork's copy is not updated on GitHub's servers yet. To do that, use: 2130 2131``` 2132>>> git push origin master 2133``` 2134 2135#### Step 3: Modifying our GLM Fork 2136 2137Our fork is now setup and we are ready to modify GLM to fix a bug. 2138 2139It's a good practice to make changes in our fork in a separate branch than the master branch because we can submit only one pull request per branch. 2140 2141Before creating a new branch, it's best to synchronize our fork and then create a new branch from the latest master branch. 2142 2143If we are not on the master branch, we should switch to it using: 2144``` 2145>>> git checkout master 2146``` 2147 2148To create a new branch called `bugifx`, we use: 2149``` 2150git branch bugfix 2151``` 2152 2153Once the code changes for the fix is done, we need to commit the changes: 2154``` 2155>>> git commit -m "Resolve the issue that caused problem with a specific fix #432" 2156``` 2157 2158The commit message should be as specific as possible and finished by the bug number in the [GLM GitHub issue page](https://github.com/g-truc/glm/issues) 2159 2160Finally, we need to push our changes in our branch to our GitHub fork using: 2161``` 2162>>> git push origin bugfix 2163``` 2164 2165Some things to keep in mind for a pull request: 2166* Keep it minimal: Try to make the minimum required changes to fix the issue. If we have added any debugging code, we should remove it. 2167* A fix at a time: The pull request should deal with one issue at a time only, unless two issue are so interlinked they must be fixed together. 2168* Write a test: GLM is largely unit tests. Unit tests are in `glm/test` directory. We should also add tests for the fixes we provide to ensure future regression doesn't happen. 2169* No whitespace changes: Avoid unnecessary formatting or whitespace changes in other parts of the code. Be careful with auto-format options in the code editor which can cause wide scale formatting changes. 2170* Follow [GLM Code Style](#section9_3) for consistency. 2171* Tests passes: Make sure GLM build and tests don't fail because of the changes. 2172 2173#### Step 4: Submitting a Pull Request 2174 2175We need to submit a pull request from the `bugfix` branch to GLM's master branch. 2176 2177On the fork github page, we can click on the *Pull Request* button. Then we can describe our pull request. Finally we press *Send Pull Request*. 2178 2179Please be patient and give them some time to go through it. 2180 2181The pull request review may suggest additional changes. So we can make those changes in our branch, and push those changes to our fork repository. Our pull request will always include the latest changes in our branch on GitHub, so we don't need to resubmit the pull request. 2182 2183Once your changes have been accepted, a project maintainer will merge our pull request. 2184 2185We are grateful to the users for their time and effort in contributing fixes. 2186 2187### <a name="section9_3"></a> 9.3. Coding style 2188 2189#### Indentation 2190 2191Always tabs. Never spaces. 2192 2193#### Spacing 2194 2195No space after if. Use if(blah) not if (blah). Example if/else block: 2196 2197```cpp 2198if(blah) 2199{ 2200 // yes like this 2201} 2202else 2203{ 2204 // something besides 2205} 2206``` 2207 2208Single line if blocks: 2209```cpp 2210if(blah) 2211 // yes like this 2212else 2213 // something besides 2214``` 2215 2216No spaces inside parens: 2217```cpp 2218if (blah) // No 2219if( blah ) // No 2220if ( blah ) // No 2221if(blah) // Yes 2222``` 2223 2224Use spaces before/after commas: 2225```cpp 2226someFunction(apple,bear,cat); // No 2227someFunction(apple, bear, cat); // Yes 2228``` 2229 2230Use spaces before/after use of `+, -, *, /, %, >>, <<, |, &, ^, ||, &&` operators: 2231```cpp 2232vec4 v = a + b; 2233``` 2234 2235#### Blank lines 2236 2237One blank line after the function blocks. 2238 2239#### Comments 2240 2241Always one space after the // in single line comments 2242 2243One space before // at the end of a line (that has code as well) 2244 2245Try to use // comments inside functions, to make it easier to remove a whole block via /* */ 2246 2247#### Cases 2248 2249```cpp 2250#define GLM_MY_DEFINE 76 2251 2252class myClass 2253{}; 2254 2255myClass const MyClass; 2256 2257namespace glm{ // glm namespace is for public code 2258namespace detail // glm::detail namespace is for implementation detail 2259{ 2260 float myFunction(vec2 const& V) 2261 { 2262 return V.x + V.y; 2263 } 2264 2265 float myFunction(vec2 const* const V) 2266 { 2267 return V->x + V->y; 2268 } 2269}//namespace detail 2270}//namespace glm 2271``` 2272 2273--- 2274<div style="page-break-after: always;"> </div> 2275 2276## <a name="section10"></a> 10. References 2277 2278### <a name="section10_1"></a> 10.1. OpenGL specifications 2279 2280* OpenGL 4.3 core specification 2281* [GLSL 4.30 specification](http://www.opengl.org/registry/doc/GLSLangSpec.4.30.7.diff.pdf) 2282![](media/image21.png){width="2.859722222222222in" height="1.6083333333333334in"}- [*GLU 1.3 specification*](http://www.opengl.org/documentation/specs/glu/glu1_3.pdf) 2283 2284### <a name="section10_2"></a> 10.2. External links 2285 2286* [GLM on stackoverflow](http://stackoverflow.com/search?q=GLM) 2287 2288### <a name="section10_3"></a> 10.3. Projects using GLM 2289 2290***[Leo’s Fortune](http://www.leosfortune.com/)*** 2291 2292Leo’s Fortune is a platform adventure game where you hunt down the cunning and mysterious thief that stole your gold. Available on PS4, Xbox One, PC, Mac, iOS and Android. 2293 2294Beautifully hand-crafted levels bring the story of Leo to life in this epic adventure. 2295 2296“I just returned home to find all my gold has been stolen! For some devious purpose, the thief has dropped pieces of my gold like breadcrumbs through the woods.” 2297 2298“Despite this pickle of a trap, I am left with no choice but to follow the trail.” 2299 2300“Whatever lies ahead, I must recover my fortune.” -Leopold 2301 2302![](/doc/manual/references-leosfortune.jpeg) 2303 2304![](/doc/manual/references-leosfortune2.jpg) 2305 2306[***OpenGL 4.0 Shading Language Cookbook***](http://www.packtpub.com/opengl-4-0-shading-language-cookbook/book?tag=rk/opengl4-abr1/0811) 2307 2308A set of recipes that demonstrates a wide of techniques for producing high-quality, real-time 3D graphics with GLSL 4.0, such as: 2309 2310* Using GLSL 4.0 to implement lighting and shading techniques. 2311* Using the new features of GLSL 4.0 including tessellation and geometry shaders. 2312* Using textures in GLSL as part of a wide variety of techniques from basic texture mapping to deferred shading. 2313 2314Simple, easy-to-follow examples with GLSL source code are provided, as well as a basic description of the theory behind each technique. 2315 2316![](/doc/manual/references-glsl4book.jpg) 2317 2318[***Outerra***](http://outerra.com/) 2319 2320A 3D planetary engine for seamless planet rendering from space down to the surface. Can use arbitrary resolution of elevation data, refining it to centimetre resolution using fractal algorithms. 2321 2322![](/doc/manual/references-outerra1.jpg) 2323 2324![](/doc/manual/references-outerra2.jpg) 2325 2326![](/doc/manual/references-outerra3.jpg) 2327 2328![](/doc/manual/references-outerra4.jpg) 2329 2330[***Falcor***](https://github.com/NVIDIA/Falcor) 2331 2332Real-time rendering research framework by NVIDIA. 2333 2334[***Cinder***](https://libcinder.org/) 2335 2336Cinder is a free and open source library for professional-quality creative coding in C++. 2337 2338Cinder is a C++ library for programming with aesthetic intent - the sort of development often called creative coding. This includes domains like graphics, audio, video, and computational geometry. Cinder is cross-platform, with official support for OS X, Windows, iOS, and WinRT. 2339 2340Cinder is production-proven, powerful enough to be the primary tool for professionals, but still suitable for learning and experimentation. Cinder is released under the [2-Clause BSD License](http://opensource.org/licenses/BSD-2-Clause). 2341 2342![](/doc/manual/references-cinder.png) 2343 2344[***opencloth***](http://code.google.com/p/opencloth/) 2345 2346A collection of source codes implementing cloth simulation algorithms in OpenGL. 2347 2348Simple, easy-to-follow examples with GLSL source code, as well as a basic description of the theory behind each technique. 2349 2350![](/doc/manual/references-opencloth1.png) 2351 2352![](/doc/manual/references-opencloth3.png) 2353 2354[***LibreOffice***](https://www.libreoffice.org/) 2355 2356LibreOffice includes several applications that make it the most powerful Free and Open Source office suite on the market. 2357 2358[***Are you using GLM in a project?***](mailto:glm@g-truc.net) 2359 2360### <a name="section10_4"></a> 10.4. Tutorials using GLM 2361 2362* [Sascha Willems' Vulkan examples](https://github.com/SaschaWillems/Vulkan), Examples and demos for the new Vulkan API 2363* [VKTS](https://github.com/McNopper/Vulkan) Vulkan examples using VulKan ToolS (VKTS) 2364* [*The OpenGL Samples Pack*](http://www.g-truc.net/project-0026.html#menu), samples that show how to set up all the different new features 2365* [*Learning Modern 3D Graphics programming*](http://www.arcsynthesis.org/gltut/), a great OpenGL tutorial using GLM by Jason L. McKesson 2366* [*Morten Nobel-Jørgensen’s*](http://blog.nobel-joergensen.com/2011/04/02/glm-brilliant-math-library-for-opengl/) review and use an [*OpenGL renderer*](https://github.com/mortennobel/RenderE) 2367* [*Swiftless’ OpenGL tutorial*](http://www.swiftless.com/opengltuts.html) using GLM by Donald Urquhart 2368* [*Rastergrid*](http://rastergrid.com/blog/), many technical articles with companion programs using GLM by Daniel Rákos\ 2369* [*OpenGL Tutorial*](http://www.opengl-tutorial.org), tutorials for OpenGL 3.1 and later 2370* [*OpenGL Programming on Wikibooks*](http://en.wikibooks.org/wiki/OpenGL_Programming): For beginners who are discovering OpenGL. 2371* [*3D Game Engine Programming*](http://3dgep.com/): Learning the latest 3D Game Engine Programming techniques. 2372* [Game Tutorials](http://www.gametutorials.com/opengl-4-matrices-and-glm/), graphics and game programming. 2373* [open.gl](https://open.gl/), OpenGL tutorial 2374* [c-jump](http://www.c-jump.com/bcc/common/Talk3/Math/GLM/GLM.html), GLM tutorial 2375* [Learn OpenGL](http://learnopengl.com/), OpenGL tutorial 2376* [***Are you using GLM in a tutorial?***](mailto:glm@g-truc.net) 2377 2378### <a name="section10_5"></a> 10.5. Equivalent for other languages 2379 2380* [*cglm*](https://github.com/recp/cglm): OpenGL Mathematics (glm) for C. 2381* [*GlmSharp*](https://github.com/Philip-Trettner/GlmSharp): Open-source semi-generated GLM-flavored math library for .NET/C\#. 2382* [glm-js](https://github.com/humbletim/glm-js): JavaScript adaptation of the OpenGL Mathematics (GLM) C++ library interfaces 2383* [JVM OpenGL Mathematics (GLM)](https://github.com/kotlin-graphics/glm): written in Kotlin, Java compatible 2384* [JGLM](https://github.com/jroyalty/jglm) - Java OpenGL Mathematics Library 2385* [SwiftGL Math Library](https://github.com/SwiftGL/Math/blob/master/Sources/glm.swift) GLM for Swift 2386* [glm-go](https://github.com/jbowtie/glm-go): Simple linear algebra library similar in spirit to GLM 2387* [openll](https://github.com/Polkm/openll): Lua bindings for OpenGL, GLM, GLFW, OpenAL, SOIL and PhysicsFS 2388* [glm-rs](https://github.com/dche/glm-rs): GLSL mathematics for Rust programming language 2389* [glmpython](https://github.com/Queatz/glmpython): GLM math library for Python 2390 2391### <a name="section10_6"></a> 10.6. Alternatives to GLM 2392 2393* [*CML*](http://cmldev.net/): The CML (Configurable Math Library) is a free C++ math library for games and graphics. 2394* [*Eigen*](http://eigen.tuxfamily.org/): A more heavy weight math library for general linear algebra in C++. 2395* [*glhlib*](http://glhlib.sourceforge.net/): A much more than glu C library. 2396* Are you using or developing an alternative library to GLM? 2397 2398### <a name="section10_7"></a> 10.7. Acknowledgements 2399 2400GLM is developed and maintained by [*Christophe Riccio*](http://www.g-truc.net) but many contributors have made this project what it is. 2401 2402Special thanks to: 2403* Ashima Arts and Stefan Gustavson for their work on [*webgl-noise*](https://github.com/ashima/webgl-noise) which has been used for GLM noises implementation. 2404* [*Arthur Winters*](http://athile.net/library/wiki/index.php?title=Athile_Technologies) for the C++11 and Visual C++ swizzle operators implementation and tests. 2405* Joshua Smith and Christoph Schied for the discussions and the experiments around the swizzle operators implementation issues. 2406* Guillaume Chevallereau for providing and maintaining the [*nightlight build system*](http://my.cdash.org/index.php?project=GLM). 2407* Ghenadii Ursachi for GLM\_GTX\_matrix\_interpolation implementation. 2408* Mathieu Roumillac for providing some implementation ideas. 2409* [*Grant James*](http://www.zeuscmd.com/) for the implementation of all combination of none-squared matrix products. 2410* Jesse Talavera-Greenberg for his work on the manual amount other things. 2411* All the GLM users that have report bugs and hence help GLM to become a great library! 2412