Updated formating

This commit is contained in:
Christophe Riccio 2016-11-01 13:59:45 +01:00
parent 54796da2cd
commit e95fc82a4e

245
manual.md
View File

@ -656,8 +656,7 @@ Define functions to access rows or columns of a matrix easily.
<glm/gtc/matrix\_access.hpp> need to be included to use these
features.
### 4.8. GLM\_GTC\_matrix\_integer {#glm_gtc_matrix_integer .HeadingB}
------------------------------
### 4.8. GLM\_GTC\_matrix\_integer
Provide integer matrix types. Inverse and determinant functions are not
supported for these types.
@ -665,16 +664,14 @@ supported for these types.
<glm/gtc/matrix\_integer.hpp> need to be included to use these
features.
### 4.9. GLM\_GTC\_matrix\_inverse {#glm_gtc_matrix_inverse .HeadingB}
------------------------------
### 4.9. GLM\_GTC\_matrix\_inverse
Define additional matrix inverting functions.
<glm/gtc/matrix\_inverse.hpp> need to be included to use these
features.
### 4.10. GLM\_GTC\_matrix\_transform {#glm_gtc_matrix_transform .HeadingB}
---------------------------------
### 4.10. GLM\_GTC\_matrix\_transform
Define functions that generate common transformation matrices.
@ -688,8 +685,7 @@ layout of this eye space.
<glm/gtc/matrix\_transform.hpp> need to be included to use these
features.
### 4.11. GLM\_GTC\_noise {#glm_gtc_noise .HeadingB}
---------------------
### 4.11. GLM\_GTC\_noise
Define 2D, 3D and 4D procedural noise functions.
@ -743,8 +739,7 @@ height="2.6666666666666665in"}
Figure 4.11.9: glm::perlin(glm::vec4(x / 16.f, y / 16.f,
glm::vec2(0.5f)), glm::vec4(2.0f));
### 4.12. GLM\_GTC\_packing {#glm_gtc_packing .HeadingB}
-----------------------
### 4.12. GLM\_GTC\_packing
Convert scalar and vector types to packed formats. This extension can
also unpack packed data to the original format. The use of packing
@ -754,16 +749,14 @@ will be perform loselessly.
<glm/gtc/packing.hpp> need to be included to use these features.
### 4.13. GLM\_GTC\_quaternion {#glm_gtc_quaternion .HeadingB}
--------------------------
### 4.13. GLM\_GTC\_quaternion
Define a quaternion type and several quaternion operations.
<glm/gtc/quaternion.hpp> need to be included to use these
features.
### 4.14. GLM\_GTC\_random {#glm_gtc_random .HeadingB}
----------------------
### 4.14. GLM\_GTC\_random
Generate random number from various distribution methods.
@ -796,32 +789,28 @@ height="2.7395833333333335in"}
Figure 4.14.6: glm::vec4(glm::gaussRand(glm::vec3(0), glm::vec3(1)), 1);
### 4.15. GLM\_GTC\_reciprocal {#glm_gtc_reciprocal .HeadingB}
--------------------------
### 4.15. GLM\_GTC\_reciprocal
Provide hyperbolic functions: secant, cosecant, cotangent, etc.
<glm/gtc/reciprocal.hpp> need to be included to use these
functionalities.
### 4.16. GLM\_GTC\_round {#glm_gtc_round .HeadingB}
---------------------
### 4.16. GLM\_GTC\_round
Rounding operation on power of two and multiple values.
<glm/gtc/round.hpp> need to be included to use these
functionalities.
### 4.17. GLM\_GTC\_type\_aligned {#glm_gtc_type_aligned .HeadingB}
-----------------------------
### 4.17. GLM\_GTC\_type\_aligned
Aligned vector types.
<glm/gtc/type\_aligned.hpp> need to be included to use these
functionalities.
### 4.18. GLM\_GTC\_type\_precision {#glm_gtc_type_precision .HeadingB}
-------------------------------
### 4.18. GLM\_GTC\_type\_precision
Add vector and matrix types with defined precisions. Eg, i8vec4: vector
of 4 signed integer of 8 bits.
@ -831,91 +820,67 @@ of types added:
Available defines for signed 8-bit integer types (glm::i8vec\*):
GLM\_PRECISION\_LOWP\_INT8: Low precision
GLM\_PRECISION\_MEDIUMP\_INT8: Medium precision
GLM\_PRECISION\_HIGHP\_INT8: High precision (default)
* GLM\_PRECISION\_LOWP\_INT8: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT8: Medium precision
* GLM\_PRECISION\_HIGHP\_INT8: High precision (default)
Available defines for unsigned 8-bit integer types (glm::u8vec\*):
GLM\_PRECISION\_LOWP\_UINT8: Low precision
GLM\_PRECISION\_MEDIUMP\_UINT8: Medium precision
GLM\_PRECISION\_HIGHP\_UINT8: High precision (default)
* GLM\_PRECISION\_LOWP\_UINT8: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT8: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT8: High precision (default)
Available defines for signed 16-bit integer types (glm::i16vec\*):
GLM\_PRECISION\_LOWP\_INT16: Low precision
GLM\_PRECISION\_MEDIUMP\_INT16: Medium precision
GLM\_PRECISION\_HIGHP\_INT16: High precision (default)
* GLM\_PRECISION\_LOWP\_INT16: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT16: Medium precision
* GLM\_PRECISION\_HIGHP\_INT16: High precision (default)
Available defines for unsigned 16-bit integer types (glm::u16vec\*):
GLM\_PRECISION\_LOWP\_UINT16: Low precision
GLM\_PRECISION\_MEDIUMP\_UINT16: Medium precision
GLM\_PRECISION\_HIGHP\_UINT16: High precision (default)
* GLM\_PRECISION\_LOWP\_UINT16: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT16: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT16: High precision (default)
Available defines for signed 32-bit integer types (glm::i32vec\*):
GLM\_PRECISION\_LOWP\_INT32: Low precision
GLM\_PRECISION\_MEDIUMP\_INT32: Medium precision
GLM\_PRECISION\_HIGHP\_INT32: High precision (default)
* GLM\_PRECISION\_LOWP\_INT32: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT32: Medium precision
* GLM\_PRECISION\_HIGHP\_INT32: High precision (default)
Available defines for unsigned 32-bit integer types (glm::u32vec\*):
GLM\_PRECISION\_LOWP\_UINT32: Low precision
GLM\_PRECISION\_MEDIUMP\_UINT32: Medium precision
GLM\_PRECISION\_HIGHP\_UINT32: High precision (default)
* GLM\_PRECISION\_LOWP\_UINT32: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT32: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT32: High precision (default)
Available defines for signed 64-bit integer types (glm::i64vec\*):
GLM\_PRECISION\_LOWP\_INT64: Low precision
GLM\_PRECISION\_MEDIUMP\_INT64: Medium precision
GLM\_PRECISION\_HIGHP\_INT64: High precision (default)
* GLM\_PRECISION\_LOWP\_INT64: Low precision
* GLM\_PRECISION\_MEDIUMP\_INT64: Medium precision
* GLM\_PRECISION\_HIGHP\_INT64: High precision (default)
Available defines for unsigned 64-bit integer types (glm::u64vec\*):
GLM\_PRECISION\_LOWP\_UINT64: Low precision
* GLM\_PRECISION\_LOWP\_UINT64: Low precision
* GLM\_PRECISION\_MEDIUMP\_UINT64: Medium precision
* GLM\_PRECISION\_HIGHP\_UINT64: High precision (default)
GLM\_PRECISION\_MEDIUMP\_UINT64: Medium precision
Available defines for 32-bit floating-point types (glm::f32vec\*, glm::f32mat\*, glm::f32quat):
GLM\_PRECISION\_HIGHP\_UINT64: High precision (default)
* GLM\_PRECISION\_LOWP\_FLOAT32: Low precision
* GLM\_PRECISION\_MEDIUMP\_FLOAT32: Medium precision
* GLM\_PRECISION\_HIGHP\_FLOAT32: High precision (default)
Available defines for 32-bit floating-point types (glm::f32vec\*,
glm::f32mat\*, glm::f32quat):
Available defines for 64-bit floating-point types (glm::f64vec\*, glm::f64mat\*, glm::f64quat):
GLM\_PRECISION\_LOWP\_FLOAT32: Low precision
* GLM\_PRECISION\_LOWP\_FLOAT64: Low precision
* GLM\_PRECISION\_MEDIUMP\_FLOAT64: Medium precision
* GLM\_PRECISION\_HIGHP\_FLOAT64: High precision (default)
GLM\_PRECISION\_MEDIUMP\_FLOAT32: Medium precision
<glm/gtc/type\_precision.hpp> need to be included to use these functionalities.
GLM\_PRECISION\_HIGHP\_FLOAT32: High precision (default)
Available defines for 64-bit floating-point types (glm::f64vec\*,
glm::f64mat\*, glm::f64quat):
GLM\_PRECISION\_LOWP\_FLOAT64: Low precision
GLM\_PRECISION\_MEDIUMP\_FLOAT64: Medium precision
GLM\_PRECISION\_HIGHP\_FLOAT64: High precision (default)
<glm/gtc/type\_precision.hpp> need to be included to use these
functionalities.
### 4.19. GLM\_GTC\_type\_ptr {#glm_gtc_type_ptr .HeadingB}
-------------------------
### 4.19. GLM\_GTC\_type\_ptr
Handle the interaction between pointers and vector, matrix types.
@ -980,8 +945,7 @@ form of notification. *
<glm/gtc/type\_ptr.hpp> need to be included to use these features.
### 4.20. GLM\_GTC\_ulp {#glm_gtc_ulp .HeadingB}
-------------------
### 4.20. GLM\_GTC\_ulp
Allow the measurement of the accuracy of a function against a reference
implementation. This extension works on floating-point data and provides
@ -990,8 +954,7 @@ results in
<glm/gtc/ulp.hpp> need to be included to use these features.
### 4.21. GLM\_GTC\_vec1 {#glm_gtc_vec1 .HeadingB}
--------------------
### 4.21. GLM\_GTC\_vec1
Add \*vec1 types.
@ -1029,8 +992,7 @@ replacement functions.
From GLM\_GTC\_matrix\_transform extension:
<glm/gtc/matrix\_transform.hpp>
[***glScale{f, d}:
***](http://www.opengl.org/sdk/docs/man2/xhtml/glScale.xml)
[***glScale{f, d}: ***](http://www.opengl.org/sdk/docs/man2/xhtml/glScale.xml)
--------------------------------
glm::mat4 glm::scale(
@ -1114,8 +1076,7 @@ From GLM core library: <glm/glm.hpp>
From GLM core library: <glm/glm.hpp>
[***glFrustum:
***](http://www.opengl.org/sdk/docs/man2/xhtml/glFrustum.xml)
[***glFrustum:***](http://www.opengl.org/sdk/docs/man2/xhtml/glFrustum.xml)
-------------------------------
glm::mat4 glm::frustum(
@ -1163,8 +1124,7 @@ From GLM\_GTC\_matrix\_transform extension:
From GLM\_GTC\_matrix\_transform extension:
<glm/gtc/matrix\_transform.hpp>
5.2. GLM replacements for GLU functions {#glm-replacements-for-glu-functions .HeadingB}
---------------------------------------
### 5.2. GLM replacements for GLU functions
***gluLookAt: ***
@ -1305,20 +1265,17 @@ From GLM\_GTC\_matrix\_transform extension:
From GLM\_GTC\_matrix\_transform extension:
<glm/gtc/matrix\_transform.hpp>
6. Known issues {#known-issues .HeadingA}
===============
## 6. Known issues
This section reports the divergences of GLM with GLSL.
6.1. not function {#not-function .HeadingB}
-----------------
### 6.1. not function
The GLSL keyword not is also a keyword in C++. To prevent name
collisions, ensure cross compiler support and a high API consistency,
the GLSL not function has been implemented with the name not\_.
6.2. Precision qualifiers support {#precision-qualifiers-support .HeadingB}
---------------------------------
### 6.2. Precision qualifiers support
GLM supports GLSL precision qualifiers through prefixes instead of
qualifiers. For example, additionally to vec4, GLM exposes lowp\_vec4,
@ -1367,11 +1324,9 @@ By default, all the types use high precision.
---------------------------------------
---------------------------------------
7. FAQ {#faq .HeadingA}
======
## 7. FAQ
7.1 Why GLM follows GLSL specification and conventions? {#why-glm-follows-glsl-specification-and-conventions .HeadingB}
-------------------------------------------------------
### 7.1 Why GLM follows GLSL specification and conventions?
Following GLSL conventions is a really strict policy of GLM. It has been
designed following the idea that everyone does its own math library with
@ -1380,18 +1335,15 @@ ARB) worked together and agreed to make GLSL. Following GLSL conventions
is a way to find consensus. Moreover, basically when a developer knows
GLSL, he knows GLM.
7.2. Does GLM run GLSL program? {#does-glm-run-glsl-program .HeadingB}
-------------------------------
### 7.2. Does GLM run GLSL program?
No, GLM is a C++ implementation of a subset of GLSL.
7.3. Does a GLSL compiler build GLM codes? {#does-a-glsl-compiler-build-glm-codes .HeadingB}
------------------------------------------
### 7.3. Does a GLSL compiler build GLM codes?
No, this is not what GLM attends to do.
7.4. Should I use GTX extensions? {#should-i-use-gtx-extensions .HeadingB}
-----------------------------------
### 7.4. Should I use GTX extensions?
GTX extensions are qualified to be experimental extensions. In GLM this
means that these extensions might change from version to version without
@ -1402,31 +1354,25 @@ features and implementations and APIs and then are promoted to GTC
extensions. This is fairly the way OpenGL features are developed;
through extensions.
7.5. Where can I ask my questions? {#where-can-i-ask-my-questions .HeadingB}
----------------------------------
### 7.5. Where can I ask my questions?
A good place is the *[OpenGL
Toolkits](http://www.opengl.org/discussion_boards/ubbthreads.php?ubb=postlist&Board=10&page=1)
forum* on [OpenGL.org](http://www.opengl.org/).
A good place is [stackoverflow](http://stackoverflow.com/search?q=GLM) using the GLM tag.
7.6. Where can I find the documentation of extensions? {#where-can-i-find-the-documentation-of-extensions .HeadingB}
------------------------------------------------------
### 7.6. Where can I find the documentation of extensions?
The 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
view of all GLM capabilities!
7.7. Should I use using namespace glm;? {#should-i-use-using-namespace-glm .HeadingB}
-----------------------------------------
### 7.7. Should I use using namespace glm;?
NO! 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
glm; will a higher compatibility with third party library and SDKs.
7.8. Is GLM fast? {#is-glm-fast .HeadingB}
-----------------
### 7.8. Is GLM fast?
GLM is mainly designed to be convenient and that's why it is written
against the GLSL specification.
@ -1441,8 +1387,7 @@ optimized code for functions of its implementation.
However, on performance critical code paths, we should expect that
dedicated algorithms should be written to reach peak performance.
7.9. When I build with Visual C++ with /W4 warning level, I have warnings... {#when-i-build-with-visual-c-with-w4-warning-level-i-have-warnings... .HeadingB}
----------------------------------------------------------------------------
### 7.9. When I build with Visual C++ with /W4 warning level, I have warnings...
You should not have any warnings even in /W4 mode. However, if you
expect such level for your code, then you should ask for the same level
@ -1451,29 +1396,23 @@ to the compiler by at least disabling the Visual C++ language extensions
enabled, then GLM will take advantage of them and the compiler will
generate warnings.
7.10. Why some GLM functions can crash because of division by zero? {#why-some-glm-functions-can-crash-because-of-division-by-zero .HeadingB}
-------------------------------------------------------------------
### 7.10. Why some GLM functions can crash because of division by zero?
GLM functions crashing is the result of a domain error that follows the
precedent given by C and C++ libraries. For example, its a domain error
to pass a null vector to glm::normalize function.
7.11. What unit for angles is used in GLM? {#what-unit-for-angles-is-used-in-glm .HeadingB}
------------------------------------------
### 7.11. What unit for angles is used in GLM?
GLSL 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
GLSL 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
the [link](http://www.g-truc.net/post-0693.html#menu).
8. Code samples {#code-samples .HeadingA}
===============
## 8. Code samples
This series of samples only shows various GLM features without
consideration of any sort.
8.1. Compute a triangle normal {#compute-a-triangle-normal .HeadingB}
------------------------------
### 8.1. Compute a triangle normal
-------------------------------------------------------------------
\#include <glm/glm.hpp> // vec3 normalize cross
@ -1522,8 +1461,7 @@ consideration of any sort.
-------------------------------------------------------------------
-------------------------------------------------------------------
8.2. Matrix transform {#matrix-transform .HeadingB}
---------------------
### 8.2. Matrix transform
---------------------------------------------------------------------
// vec3, vec4, ivec4, mat4
@ -1588,8 +1526,7 @@ consideration of any sort.
---------------------------------------------------------------------
---------------------------------------------------------------------
8.3. Vector types {#vector-types .HeadingB}
-----------------
### 8.3. Vector types
---------------------------------------------------------------------------
\#include <glm/glm.hpp> //vec2
@ -1672,8 +1609,7 @@ consideration of any sort.
---------------------------------------------------------------------------
---------------------------------------------------------------------------
8.4. Lighting {#lighting .HeadingB}
-------------
### 8.4. Lighting
-----------------------------------------------------------------
\#include <glm/glm.hpp> // vec3 normalize reflect dot pow
@ -1754,44 +1690,29 @@ consideration of any sort.
-----------------------------------------------------------------
-----------------------------------------------------------------
9. References {#references .HeadingA}
=============
## 9. References
9.1. GLM development {#glm-development .HeadingB}
--------------------
### 9.1. GLM development
- [GLM website](http://glm.g-truc.net)
* [GLM website](http://glm.g-truc.net)
![](media/image20.png){width="2.870138888888889in"
height="1.6145833333333333in"}- [GLM HEAD
snapshot](https://github.com/g-truc/glm/archive/master.zip)
- GLM bug report and feature request
* GLM bug report and feature request
- [G-Truc Creations page](http://www.g-truc.net/project-0016.html)
### 9.2. OpenGL specifications
9.2. OpenGL specifications {#opengl-specifications .HeadingB}
--------------------------
* OpenGL 4.3 core specification
* [GLSL 4.30 specification](http://www.opengl.org/registry/doc/GLSLangSpec.4.30.7.diff.pdf)
![](media/image21.png){width="2.859722222222222in" height="1.6083333333333334in"}- [*GLU 1.3 specification*](http://www.opengl.org/documentation/specs/glu/glu1_3.pdf)
- OpenGL 4.3 core specification
### 9.3. External links
- [GLSL 4.30
specification](http://www.opengl.org/registry/doc/GLSLangSpec.4.30.7.diff.pdf)
* [GLM on stackoverflow](http://stackoverflow.com/search?q=GLM)
![](media/image21.png){width="2.859722222222222in"
height="1.6083333333333334in"}- [*GLU 1.3
specification*](http://www.opengl.org/documentation/specs/glu/glu1_3.pdf)
9.3. External links {#external-links .HeadingB}
-------------------
- [*The OpenGL Toolkits forum to ask questions about
GLM*](http://www.opengl.org/discussion_boards/ubbthreads.php?ubb=postlist&Board=10&page=1)
- [GLM on stackoverflow](http://stackoverflow.com/search?q=GLM)
![](media/image22.png){width="2.870138888888889in" height="1.6145833333333333in"}9.4. Projects using GLM {#projects-using-glm .HeadingB}
---------------------------------------------------------------------------------------------------------
### 9.4. Projects using GLM
***[Leos Forture](http://www.leosfortune.com/) ***