diff --git a/manual.md b/manual.md index c4391955..5db83faa 100644 --- a/manual.md +++ b/manual.md @@ -12,7 +12,7 @@ + [1.2. Faster compilation](#section1_2) + [1.3. Example usage](#section1_3) + [1.4. Dependencies](#section1_4) -+ [2. Preprocessor options](#section2) ++ [2. Preprocessor configurations](#section2) + [2.1. GLM\_FORCE\_SWIZZLE: Enable swizzle operators](#section2_1) + [2.2. GLM\_FORCE\_SWIZZLE: Enable swizzle functions](#section2_2) + [2.3. GLM\_FORCE\_XYZW\_ONLY: Only exposes x, y, z and w components](#section2_3) @@ -98,7 +98,7 @@ ### The Happy Bunny License (Modified MIT License) -Copyright (c) 2005 - 2017 G-Truc Creation +Copyright (c) 2005 - G-Truc Creation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -126,7 +126,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ### The MIT License -Copyright (c) 2005 - 2017 G-Truc Creation +Copyright (c) 2005 - G-Truc Creation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -152,63 +152,92 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. --- ## 1. Getting started -### 1.1. Setup +### 1.1. Using global headers -GLM 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 `` header. The library can also be installed with CMake, though the details of doing so will differ depending on the target build system. - -Features can also be included individually to shorten compilation times. +GLM 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 `` header: ```cpp -#include // vec2, bvec2, dvec2, ivec2 and uvec2 -#include // vec3, bvec3, dvec3, ivec3 and uvec3 -#include // vec4, bvec4, dvec4, ivec4 and uvec4 -#include // mat2, dmat2 -#include // mat2x3, dmat2x3 -#include // mat2x4, dmat2x4 -#include // mat3x2, dmat3x2 -#include // mat3, dmat3 -#include // mat3x4, dmat2 -#include // mat4x2, dmat4x2 -#include // mat4x3, dmat4x3 -#include // mat4, dmat4 -#include // all the GLSL common functions -#include // all the GLSL exponential functions -#include // all the GLSL geometry functions -#include // all the GLSL integer functions -#include // all the GLSL matrix functions -#include // all the GLSL packing functions -#include // all the GLSL trigonometric functions -#include // all the GLSL vector relational functions +#include ``` -### 1.2. Faster compilation -GLM uses C++ templates heavily, and may significantly increase compilation times for projects that use it. Hence, source files should only include the headers they actually use. +Using GLM through headers including everything: +```cpp +// Include all GLM core / GLSL features +#include // vec2, vec3, mat4, radians -To reduce compilation time, we can include ``, which forward-declares all types should their definitions not be needed. - -```cpp -// Header file (forward declarations only) -#include +// Include all GLM extensions +#include // perspective, translate, rotate -// At this point, we don't care what exactly makes up a vec2; that won't matter -// until we write this function's implementation. -glm::vec2 functionDeclaration(const glm::vec2& input); +glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, glm::vec3 const& Up) +{ + glm::mat4 Proj = glm::perspective(glm::radians(45.f), 1.33f, 0.1f, 10.f); + glm::mat4 ViewTranslate = glm::translate(glm::mat4(1.f), Translate); + glm::mat4 ViewRotateX = glm::rotate(ViewTranslate, Orientation.y, Up); + glm::mat4 View = glm::rotate(ViewRotateX, Orientation.x, Up); + glm::mat4 Model = glm::mat4(1.0f); + return Proj * View * Model; +} ``` -Precompiled headers will also be helpful, though are not covered by this manual. +### 1.2. Using separated headers -### 1.3. Example usage +GLM 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: +```cpp +#include // vec2, bvec2, dvec2, ivec2 and uvec2 +#include // vec3, bvec3, dvec3, ivec3 and uvec3 +#include // vec4, bvec4, dvec4, ivec4 and uvec4 +#include // mat2, dmat2 +#include // mat2x3, dmat2x3 +#include // mat2x4, dmat2x4 +#include // mat3x2, dmat3x2 +#include // mat3, dmat3 +#include // mat3x4, dmat2 +#include // mat4x2, dmat4x2 +#include // mat4x3, dmat4x3 +#include // mat4, dmat4 +#include // all the GLSL common functions: abs, min, mix, isnan, fma, etc. +#include // all the GLSL exponential functions: pow, log, exp2, sqrt, etc. +#include // all the GLSL geometry functions: dot, cross, reflect, etc. +#include // all the GLSL integer functions: findMSB, bitfieldExtract, etc. +#include // all the GLSL matrix functions: transpose, inverse, etc. +#include // all the GLSL packing functions: packUnorm4x8, unpackHalf2x16, etc. +#include // all the GLSL trigonometric functions: radians, cos, asin, etc. +#include // all the GLSL vector relational functions: equal, less, etc. +``` +Using GLM through headers including features separated following the structure of GLSL specifications: ```cpp // Include GLM core features -#include -#include -#include -#include +#include // vec2 +#include // vec3 +#include // mat4 +#include //radians // Include GLM extensions -#include +#include // perspective, translate, rotate + +glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, glm::vec3 const& Up) +{ + glm::mat4 Proj = glm::perspective(glm::radians(45.f), 1.33f, 0.1f, 10.f); + glm::mat4 ViewTranslate = glm::translate(glm::mat4(1.f), Translate); + glm::mat4 ViewRotateX = glm::rotate(ViewTranslate, Orientation.y, Up); + glm::mat4 View = glm::rotate(ViewRotateX, Orientation.x, Up); + glm::mat4 Model = glm::mat4(1.0f); + return Proj * View * Model; +} +``` + +### 1.3. Using extension headers + +Using GLM through split headers to minimize the project build time: +```cpp +// Include GLM extensions +#include // vec2 +#include // vec3 +#include // mat4 +#include // perspective, translate, rotate +#include // radians glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, glm::vec3 const& Up) {