mirror of
https://github.com/g-truc/glm.git
synced 2024-11-22 08:54:35 +00:00
docs(manual): some markdown fixes
- Add a blank line before block elements (lists, code blocks, etc) - Remove trailing whitespace - Use "plaintext" language for code blocks when appropriate - Fix duplicated section3_4 anchor - Fix <` to `< in section 4.10 - Always referece images relative to the current directory - Use markdown-style link instead of HTML href in section 7.13 - Remove extra space before closing emphasis in section 4.18
This commit is contained in:
Andrea Pappacoda
parent
cc98465e35
commit
b4a09f5ac0
102
manual.md
102
manual.md
@ -8,6 +8,7 @@
|
||||
<div style="page-break-after: always;"> </div>
|
||||
|
||||
## Table of Contents
|
||||
|
||||
+ [0. Licenses](#section0)
|
||||
+ [1. Getting started](#section1)
|
||||
+ [1.1. Using global headers](#section1_1)
|
||||
@ -170,6 +171,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
<div style="page-break-after: always;"> </div>
|
||||
|
||||
## <a name="section1"></a> 1. Getting started
|
||||
|
||||
### <a name="section1_1"></a> 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 `<glm/glm.hpp>` header:
|
||||
@ -179,6 +181,7 @@ GLM is a header-only library, and thus does not need to be compiled. We can use
|
||||
```
|
||||
|
||||
To 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:
|
||||
|
||||
```cpp
|
||||
// Include all GLM core / GLSL features
|
||||
#include <glm/glm.hpp> // vec2, vec3, mat4, radians
|
||||
@ -202,6 +205,7 @@ glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, gl
|
||||
### <a name="section1_2"></a> 1.2. Using separated headers
|
||||
|
||||
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. Following is the list of all the core features, based on GLSL specification, headers:
|
||||
|
||||
```cpp
|
||||
#include <glm/vec2.hpp> // vec2, bvec2, dvec2, ivec2 and uvec2
|
||||
#include <glm/vec3.hpp> // vec3, bvec3, dvec3, ivec3 and uvec3
|
||||
@ -226,6 +230,7 @@ GLM relies on C++ templates heavily, and may significantly increase compilation
|
||||
```
|
||||
|
||||
The following is a code sample using separated core headers and an extension:
|
||||
|
||||
```cpp
|
||||
// Include GLM core features
|
||||
#include <glm/vec2.hpp> // vec2
|
||||
@ -250,6 +255,7 @@ glm::mat4 transform(glm::vec2 const& Orientation, glm::vec3 const& Translate, gl
|
||||
### <a name="section1_3"></a> 1.3. Using extension headers
|
||||
|
||||
Using GLM through split headers to minimize the project build time:
|
||||
|
||||
```cpp
|
||||
// Include GLM vector extensions:
|
||||
#include <glm/ext/vector_float2.hpp> // vec2
|
||||
@ -319,7 +325,8 @@ Using `GLM_FORCE_MESSAGES`, GLM will report the configuration as part of the bui
|
||||
```
|
||||
|
||||
Example of configuration log generated by `GLM_FORCE_MESSAGES`:
|
||||
```cpp
|
||||
|
||||
```plaintext
|
||||
GLM: version 0.9.9.1
|
||||
GLM: C++ 17 with extensions
|
||||
GLM: Clang compiler detected
|
||||
@ -361,6 +368,7 @@ any inclusion of `<glm/glm.hpp>` to restrict the language feature set C++98:
|
||||
```
|
||||
|
||||
For C++11, C++14, and C++17 equivalent defines are available:
|
||||
|
||||
* `GLM_FORCE_CXX11`
|
||||
* `GLM_FORCE_CXX14`
|
||||
* `GLM_FORCE_CXX17`
|
||||
@ -741,7 +749,6 @@ int average(int const A, int const B)
|
||||
When 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.
|
||||
GLM relies on anonymous structs for swizzle operators and aligned vector types. To silent those warnings define `GLM_FORCE_SILENT_WARNINGS` before including GLM headers.
|
||||
|
||||
|
||||
### <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
|
||||
|
||||
By 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.
|
||||
@ -1024,7 +1031,7 @@ This extension exposes double-precision floating point vector with 4 components
|
||||
|
||||
Include `<glm/ext/vector_double4_precision.hpp>` to use these features.
|
||||
|
||||
### <a name="section3_4"></a> 3.5. Vector functions
|
||||
### <a name="section3_5"></a> 3.5. Vector functions
|
||||
|
||||
#### 3.5.1. GLM_EXT_vector_common
|
||||
|
||||
@ -1519,41 +1526,41 @@ projective matrix functions (`perspective`, `ortho`, etc) are designed to expect
|
||||
|
||||
Define 2D, 3D and 4D procedural noise functions.
|
||||
|
||||
<`glm/gtc/noise.hpp>` need to be included to use these features.
|
||||
`<glm/gtc/noise.hpp>` need to be included to use these features.
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.1: glm::simplex(glm::vec2(x / 16.f, y / 16.f));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.2: glm::simplex(glm::vec3(x / 16.f, y / 16.f, 0.5f));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.3: glm::simplex(glm::vec4(x / 16.f, y / 16.f, 0.5f, 0.5f));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.4: glm::perlin(glm::vec2(x / 16.f, y / 16.f));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.5: glm::perlin(glm::vec3(x / 16.f, y / 16.f, 0.5f));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.6: glm::perlin(glm::vec4(x / 16.f, y / 16.f, 0.5f, 0.5f)));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.7: glm::perlin(glm::vec2(x / 16.f, y / 16.f), glm::vec2(2.0f));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.8: glm::perlin(glm::vec3(x / 16.f, y / 16.f, 0.5f), glm::vec3(2.0f));
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.10.9: glm::perlin(glm::vec4(x / 16.f, y / 16.f, glm::vec2(0.5f)), glm::vec4(2.0f));
|
||||
|
||||
@ -1575,27 +1582,27 @@ Probability distributions in up to four dimensions.
|
||||
|
||||
`<glm/gtc/random.hpp>` need to be included to use these features.
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.13.1: glm::vec4(glm::linearRand(glm::vec2(-1), glm::vec2(1)), 0, 1);
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.13.2: glm::vec4(glm::circularRand(1.0f), 0, 1);
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.13.3: glm::vec4(glm::sphericalRand(1.0f), 1);
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.13.4: glm::vec4(glm::diskRand(1.0f), 0, 1);
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.13.5: glm::vec4(glm::ballRand(1.0f), 1);
|
||||
|
||||
|
||||
|
||||
|
||||
Figure 4.13.6: glm::vec4(glm::gaussRand(glm::vec3(0), glm::vec3(1)), 1);
|
||||
|
||||
@ -1657,7 +1664,7 @@ void foo()
|
||||
```
|
||||
|
||||
*Note: It would be possible to implement [`glVertex3fv`](http://www.opengl.org/sdk/docs/man2/xhtml/glVertex.xml)(glm::vec3(0)) in C++ with the appropriate cast operator that would result as an
|
||||
implicit cast in this example. However cast operators may produce programs running with unexpected behaviours without build error or any form of notification. *
|
||||
implicit cast in this example. However cast operators may produce programs running with unexpected behaviours without build error or any form of notification.*
|
||||
|
||||
`<glm/gtc/type_ptr.hpp>` need to be included to use these features.
|
||||
|
||||
@ -1933,7 +1940,7 @@ To workaround the incompatibility with these macros, GLM will systematically und
|
||||
|
||||
### <a name="section7_13"></a> 7.13. Constant expressions support
|
||||
|
||||
GLM 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.
|
||||
GLM has some C++ [constant expressions](http://en.cppreference.com/w/cpp/language/constexpr) support. However, GLM automatically detects the use of SIMD instruction sets through compiler arguments to populate its implementation with SIMD intrinsics.
|
||||
Unfortunately, GCC and Clang doesn't support SIMD instrinsics as constant expressions. To allow constant expressions on all vectors and matrices types, define `GLM_FORCE_PURE` before including GLM headers.
|
||||
|
||||
---
|
||||
@ -2091,7 +2098,8 @@ Additional, bugs can be configuration specific. We can report the configuration
|
||||
```
|
||||
|
||||
An example of build messages generated by GLM:
|
||||
```
|
||||
|
||||
```plaintext
|
||||
GLM: 0.9.9.1
|
||||
GLM: C++ 17 with extensions
|
||||
GLM: GCC compiler detected"
|
||||
@ -2117,7 +2125,7 @@ The tutorial assumes you have some basic understanding of git concepts - reposit
|
||||
We will make our changes in our own copy of the GLM sitory. On the GLM GitHub repo and we press the Fork button.
|
||||
We need to download a copy of our fork to our local machine. In the terminal, type:
|
||||
|
||||
```
|
||||
```plaintext
|
||||
>>> git clone <our-repository-fork-git-url>
|
||||
```
|
||||
|
||||
@ -2129,25 +2137,25 @@ We can find our repository git url on the Github reposotory page. The url looks
|
||||
|
||||
We 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.
|
||||
|
||||
```
|
||||
```plaintext
|
||||
>>> git remote add upstream https://github.com/processing/processing.git
|
||||
```
|
||||
|
||||
To synchronize our fork to the latest commit in the GLM repository, we can use the following command:
|
||||
|
||||
```
|
||||
```plaintext
|
||||
>>> git fetch upstream
|
||||
```
|
||||
|
||||
Then, we can merge the remote master branch to our current branch:
|
||||
|
||||
```
|
||||
```plaintext
|
||||
>>> git merge upstream/master
|
||||
```
|
||||
|
||||
Now 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:
|
||||
|
||||
```
|
||||
```plaintext
|
||||
>>> git push origin master
|
||||
```
|
||||
|
||||
@ -2160,28 +2168,33 @@ It's a good practice to make changes in our fork in a separate branch than the m
|
||||
Before creating a new branch, it's best to synchronize our fork and then create a new branch from the latest master branch.
|
||||
|
||||
If we are not on the master branch, we should switch to it using:
|
||||
```
|
||||
|
||||
```plaintext
|
||||
>>> git checkout master
|
||||
```
|
||||
|
||||
To create a new branch called `bugifx`, we use:
|
||||
```
|
||||
|
||||
```plaintext
|
||||
git branch bugfix
|
||||
```
|
||||
|
||||
Once the code changes for the fix is done, we need to commit the changes:
|
||||
```
|
||||
|
||||
```plaintext
|
||||
>>> git commit -m "Resolve the issue that caused problem with a specific fix #432"
|
||||
```
|
||||
|
||||
The 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)
|
||||
|
||||
Finally, we need to push our changes in our branch to our GitHub fork using:
|
||||
```
|
||||
|
||||
```plaintext
|
||||
>>> git push origin bugfix
|
||||
```
|
||||
|
||||
Some things to keep in mind for a pull request:
|
||||
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
@ -2225,6 +2238,7 @@ else
|
||||
```
|
||||
|
||||
Single line if blocks:
|
||||
|
||||
```cpp
|
||||
if(blah)
|
||||
// yes like this
|
||||
@ -2233,6 +2247,7 @@ else
|
||||
```
|
||||
|
||||
No spaces inside parens:
|
||||
|
||||
```cpp
|
||||
if (blah) // No
|
||||
if( blah ) // No
|
||||
@ -2241,12 +2256,14 @@ if(blah) // Yes
|
||||
```
|
||||
|
||||
Use spaces before/after commas:
|
||||
|
||||
```cpp
|
||||
someFunction(apple,bear,cat); // No
|
||||
someFunction(apple, bear, cat); // Yes
|
||||
```
|
||||
|
||||
Use spaces before/after use of `+, -, *, /, %, >>, <<, |, &, ^, ||, &&` operators:
|
||||
|
||||
```cpp
|
||||
vec4 v = a + b;
|
||||
```
|
||||
@ -2261,7 +2278,7 @@ Always one space after the // in single line comments
|
||||
|
||||
One space before // at the end of a line (that has code as well)
|
||||
|
||||
Try to use // comments inside functions, to make it easier to remove a whole block via /* */
|
||||
Try to use // comments inside functions, to make it easier to remove a whole block via /\* \*/
|
||||
|
||||
#### Cases
|
||||
|
||||
@ -2318,9 +2335,9 @@ Beautifully hand-crafted levels bring the story of Leo to life in this epic adve
|
||||
|
||||
“Whatever lies ahead, I must recover my fortune.” -Leopold
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[***OpenGL 4.0 Shading Language Cookbook***](http://www.packtpub.com/opengl-4-0-shading-language-cookbook/book?tag=rk/opengl4-abr1/0811)
|
||||
|
||||
@ -2332,19 +2349,19 @@ A set of recipes that demonstrates a wide of techniques for producing high-quali
|
||||
|
||||
Simple, easy-to-follow examples with GLSL source code are provided, as well as a basic description of the theory behind each technique.
|
||||
|
||||
|
||||
|
||||
|
||||
[***Outerra***](http://outerra.com/)
|
||||
|
||||
A 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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[***Falcor***](https://github.com/NVIDIA/Falcor)
|
||||
|
||||
@ -2358,7 +2375,7 @@ Cinder is a C++ library for programming with aesthetic intent - the sort of dev
|
||||
|
||||
Cinder 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).
|
||||
|
||||
|
||||
|
||||
|
||||
[***opencloth***](https://github.com/mmmovania/opencloth/)
|
||||
|
||||
@ -2366,9 +2383,9 @@ A collection of source codes implementing cloth simulation algorithms in OpenGL.
|
||||
|
||||
Simple, easy-to-follow examples with GLSL source code, as well as a basic description of the theory behind each technique.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[***LibreOffice***](https://www.libreoffice.org/)
|
||||
|
||||
@ -2419,6 +2436,7 @@ LibreOffice includes several applications that make it the most powerful Free an
|
||||
GLM is developed and maintained by [*Christophe Riccio*](http://www.g-truc.net) but many contributors have made this project what it is.
|
||||
|
||||
Special thanks to:
|
||||
|
||||
* 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.
|
||||
* [*Arthur Winters*](http://athile.net/library/wiki/index.php?title=Athile_Technologies) for the C++11 and Visual C++ swizzle operators implementation and tests.
|
||||
* Joshua Smith and Christoph Schied for the discussions and the experiments around the swizzle operators implementation issues.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user