mirror/glm
1
0
Fork 0
mirror of https://github.com/g-truc/glm.git synced 2024-09-20 00:12:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

Proofreading and editing from #458

Browse Source
This commit is contained in:
Christophe Riccio 2016-11-01 22:22:50 +01:00
parent 2488eb6d3f
commit 2c4e8bf83a
2 changed files with 47 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
manual.md
View File

@ -140,8 +140,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
## 1. Getting started <a name="section1"></a>
### 1.1. Setup <a name="section1_1"></a>
GLM is a header only library. Hence, there is nothing to build to use it. To use GLM, a programmer only has to include &lt;glm/glm.hpp&gt; in his program. This include provides all the GLSL features implemented by
GLM.
GLM is a header only library. Hence, there is nothing to build to use it. To use GLM, merely include &lt;glm/glm.hpp&gt; header. This include provides all the GLSL features implemented by GLM.
Core GLM features can be included using individual headers to allow faster user program compilations.
@ -177,10 +176,10 @@ included only in program sources using them.
To further help compilation time, GLM 0.9.5 introduced &lt;glm/fwd.hpp&gt; that provides forward declarations of GLM types.
```cpp
// Header file
// Header file (forward declarations only)
#include <glm/fwd.hpp>
// Source file
// Source file (actual implementation)
#include <glm/glm.hpp>;
```
@ -333,7 +332,7 @@ void foo()
### 3.1. Default precision <a name="section3_1"></a>
In C++, it is not possible to implement GLSL default precision (GLSL 4.10 specification section 4.5.3) using GLSL syntax.
C++ does not provide a way to implement GLSL default precision selection (as defined in GLSL 4.10 specification section 4.5.3) with GLSL-like syntax.
```cpp
precision mediump int;
@ -615,7 +614,7 @@ Fast bitfield operations on scalar and vector variables.
### 4.2. GLM_GTC_color_space <a name="section4_2"></a>
Conversion between linear RGB to sRGB and sRGB to linear RGB.
Conversion between linear RGB and sRGB color spaces.
&lt;glm/gtc/color\_space.hpp&gt; need to be included to use these features.
@ -627,7 +626,7 @@ Provide a list of built-in constants.
### 4.4. GLM\_GTC\_epsilon <a name="section4_4"></a>
Approximate equal and not equal comparisons with selectable epsilon.
Approximate equality comparisons for floating-point numbers, possibly with a user-defined epsilon.
&lt;glm/gtc/epsilon.hpp&gt; need to be included to use these features.
@ -639,34 +638,36 @@ Useful functions.
### 4.6. GLM\_GTC\_integer <a name="section4_6"></a>
Provide integer variants of GLM core functions.
Integer variants of core GLM functions.
&lt;glm/gtc/integer.hpp&gt; need to be included to use these features.
### 4.7. GLM\_GTC\_matrix\_access <a name="section4_7"></a>
Define functions to access rows or columns of a matrix easily.
Functions to conveniently access the individual rows or columns of a matrix.
&lt;glm/gtc/matrix\_access.hpp&gt; need to be included to use these features.
### 4.8. GLM\_GTC\_matrix\_integer <a name="section4_8"></a>
Provide integer matrix types. Inverse and determinant functions are not supported for these types.
Integer matrix types similar to the core floating-point matrices. Some operations (such as inverse and determinant) are not supported.
&lt;glm/gtc/matrix\_integer.hpp&gt; need to be included to use these features.
### 4.9. GLM\_GTC\_matrix\_inverse <a name="section4_9"></a>
Define additional matrix inverting functions.
Additional matrix inverse functions.
&lt;glm/gtc/matrix\_inverse.hpp&gt; need to be included to use these features.
### 4.10. GLM\_GTC\_matrix\_transform <a name="section4_10"></a>
Define functions that generate common transformation matrices.
Matrix transformation functions that follow the OpenGL fixed-function conventions.
The 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
projective matrix functions (perspective, ortho, etc) are designed to expect. The OpenGL compatibility specifications define the particular layout of this eye space.
For 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.
The 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
projective matrix functions (***perspective***, ***ortho***, etc) are designed to expect. The OpenGL compatibility specifications define the particular layout of this eye space.
&lt;glm/gtc/matrix\_transform.hpp&gt; need to be included to use these features.
@ -714,20 +715,19 @@ Figure 4.11.9: glm::perlin(glm::vec4(x / 16.f, y / 16.f, glm::vec2(0.5f)), glm::
### 4.12. GLM\_GTC\_packing <a name="section4_12"></a>
Convert scalar and vector types to packed formats. This extension can also unpack packed data to the original format. The use of packing functions will results in precision lost. However, the extension
guarantee that packing a value previously unpacked from the same format will be perform loselessly.
Convert 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.
&lt;glm/gtc/packing.hpp&gt; need to be included to use these features.
### 4.13. GLM\_GTC\_quaternion <a name="section4_13"></a>
Define a quaternion type and several quaternion operations.
Quaternions and operations upon thereof.
&lt;glm/gtc/quaternion.hpp&gt; need to be included to use these features.
### 4.14. GLM\_GTC\_random <a name="section4_14"></a>
Generate random number from various distribution methods.
Probability distributions in up to four dimensions.
&lt;glm/gtc/random.hpp&gt; need to be included to use these features.
@ -757,13 +757,13 @@ Figure 4.14.6: glm::vec4(glm::gaussRand(glm::vec3(0), glm::vec3(1)), 1);
### 4.15. GLM\_GTC\_reciprocal <a name="section4_15"></a>
Provide hyperbolic functions: secant, cosecant, cotangent, etc.
Reciprocal trigonometric functions (e.g. secant, cosecant, tangent).
&lt;glm/gtc/reciprocal.hpp&gt; need to be included to use these functionalities.
### 4.16. GLM\_GTC\_round <a name="section4_16"></a>
Rounding operation on power of two and multiple values.
Various rounding operations and common special cases thereof.
&lt;glm/gtc/round.hpp&gt; need to be included to use these functionalities.
@ -775,9 +775,9 @@ Aligned vector types.
### 4.18. GLM\_GTC\_type\_precision <a name="section4_18"></a>
Add vector and matrix types with defined precisions. Eg, i8vec4: vector of 4 signed integer of 8 bits.
Vector and matrix types with defined precisions, e.g. i8vec4, which is a 4D vector of signed 8-bit integers.
This extension adds defines to set the default precision of each class of types added:
This extension adds defines to set the default precision of each class of types added, in a manner identical to that described in section [Default precision](#section3_1).
Available defines for signed 8-bit integer types (glm::i8vec\*):
@ -843,20 +843,14 @@ Available defines for 64-bit floating-point types (glm::f64vec\*, glm::f64mat\*,
### 4.19. GLM\_GTC\_type\_ptr <a name="section4_19"></a>
Handle the interaction between pointers and vector, matrix types.
Facilitate interactions between pointers to basic types (e.g. float*) and GLM types (e.g. mat4).
This extension defines an overloaded function, glm::value\_ptr, which
takes any of the core template types (vec3, mat4, etc.). It returns a
pointer to the memory layout of the object. Matrix types store their
values in column-major order.
This is useful for uploading data to matrices or copying data to buffer
objects.
This 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.
```cpp
// GLM\_GTC\_type\_ptr extension provides a safe solution:
// GLM_GTC_type_ptr provides a safe solution:
#include <glm/glm.hpp>
#include &lt;glm/gtc/type\_ptr.hpp&gt;
#include <glm/gtc/type_ptr.hpp>
void foo()
{
@ -867,7 +861,7 @@ void foo()
glLoadMatrixfv(glm::value_ptr(m));
}
// Another solution inspired by STL:
// Another solution, this one inspired by the STL:
#include <glm/glm.hpp>
void foo()
@ -887,7 +881,7 @@ implicit cast in this example. However cast operators may produce programs runni
### 4.20. GLM\_GTC\_ulp <a name="section4_20"></a>
Allow the measurement of the accuracy of a function against a reference implementation. This extension works on floating-point data and provides results in [ULP](http://ljk.imag.fr/membres/Carine.Lucas/TPScilab/JMMuller/ulp-toms.pdf).
Measure 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).
&lt;glm/gtc/ulp.hpp&gt; need to be included to use these features.
@ -1012,7 +1006,7 @@ glm::mat4 perspective(float fovy, float aspect, float zNear, float zFar);
glm::dmat4 perspective(double fovy, double aspect, double zNear, double zFar);
```
One difference between GLM and GLU is that fovy is expressed in radians in GLM instead of degrees.
Note that in GLM, fovy is expressed in radians, not degrees.
From GLM\_GTC\_matrix\_transform extension: &lt;glm/gtc/matrix\_transform.hpp&gt;
@ -1046,19 +1040,17 @@ From GLM\_GTC\_matrix\_transform extension: &lt;glm/gtc/matrix\_transform.hpp&gt
---
## 6. Known issues <a name="section6"></a>
This section reports the divergences of GLM with GLSL.
This section reports GLSL features that GLM can't accurately emulate due to language restrictions.
### 6.1. not function <a name="section6_1"></a>
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\_.
The 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.
### 6.2. Precision qualifiers support <a name="section6_2"></a>
GLM supports GLSL precision qualifiers through prefixes instead of qualifiers. For example, additionally to vec4, GLM exposes lowp\_vec4, mediump\_vec4 and highp\_vec4 types.
GLM 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|.
Similarly to GLSL, GLM precision qualifiers are used to handle trade-off between performances and precisions of operations in term of [ULPs](http://en.wikipedia.org/wiki/Unit_in_the_last_place).
By default, all the types use high precision.
Similarly 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.
```cpp
// Using precision qualifier in GLSL:
@ -1084,6 +1076,8 @@ ivec3 foo(const vec4 & v)
}
```
The syntax for default precision specifications in GLM differs from that in GLSL; for more information, see section Default Precision <a name="section3_1"></a>.
---
## 7. FAQ <a name="section7"></a>
@ -1136,7 +1130,7 @@ You should not have any warnings even in /W4 mode. However, if you expect such l
### 7.10. Why some GLM functions can crash because of division by zero? <a name="section7_10"></a>
GLM functions crashing is the result of a domain error that follows the precedent given by C and C++ libraries. For example, it’s a domain error to pass a null vector to glm::normalize function.
GLM 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.
### 7.11. What unit for angles is used in GLM? <a name="section7_11"></a>
@ -1310,19 +1304,19 @@ Beautifully hand-crafted levels bring the story of Leo to life in this epic adve
[***OpenGL 4.0 Shading Language Cookbook***](http://www.packtpub.com/opengl-4-0-shading-language-cookbook/book?tag=rk/opengl4-abr1/0811)
A full set of recipes demonstrating simple and advanced techniques for producing high-quality, real-time 3D graphics using GLSL 4.0.
A set of recipes that demonstrates a wide of techniques for producing high-quality, real-time 3D graphics with GLSL 4.0, such as:
How to use the OpenGL Shading Language to implement lighting and shading techniques.
* Using GLSL 4.0 to implement lighting and shading techniques.
* Using the new features of GLSL 4.0 including tessellation and geometry shaders.
* Using textures in GLSL as part of a wide variety of techniques from basic texture mapping to deferred shading.
Use the new features of GLSL 4.0 including tessellation and geometry shaders.
How to use textures in GLSL as part of a wide variety of techniques from basic texture mapping to deferred shading.
Simple, easy-to-follow examples with GLSL source code are provided, as well as a basic description of the theory behind each technique.
![](/doc/manual/references-glsl4book.jpg)
[***Outerra***](http://outerra.com/)
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.
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.
![](/doc/manual/references-outerra1.jpg)
@ -1390,7 +1384,7 @@ Simple, easy-to-follow examples with GLSL source code, as well as a basic descri
* [*CML*](http://cmldev.net/): The CML (Configurable Math Library) is a free C++ math library for games and graphics.
* [*Eigen*](http://eigen.tuxfamily.org/): A more heavy weight math library for general linear algebra in C++.
* [*glhlib*](http://glhlib.sourceforge.net/): A much more than glu C library.
* Are you using or working on an alternative library to GLM?
* Are you using or developing an alternative library to GLM?
### 9.7. Acknowledgements <a name="section9_7"></a>
@ -1399,9 +1393,10 @@ GLM is developed and maintained by [*Christophe Riccio*](http://www.g-truc.net)
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 operator implementation issues.
* Joshua Smith and Christoph Schied for the discussions and the experiments around the swizzle operators implementation issues.
* Guillaume Chevallereau for providing and maintaining the [*nightlight build system*](http://my.cdash.org/index.php?project=GLM).
* Ghenadii Ursachi for GLM\_GTX\_matrix\_interpolation implementation.
* Mathieu Roumillac for providing some implementation ideas.
* [*Grant James*](http://www.zeuscmd.com/) for the implementation of all combination of none-squared matrix products.
* Jesse Talavera-Greenberg for his work on the manual amount other things.
* All the GLM users that have report bugs and hence help GLM to become a great library!

5
readme.md
View File

@ -2,7 +2,7 @@
[OpenGL Mathematics](http://glm.g-truc.net/) (*GLM*) is a header only C++ mathematics library for graphics software based on the [OpenGL Shading Language (GLSL) specifications](https://www.opengl.org/registry/doc/GLSLangSpec.4.50.diff.pdf).
*GLM* provides classes and functions designed and implemented with the same naming conventions and functionalities than *GLSL* so that anyone who knows *GLSL*, can use *GLM* as well in C++.
*GLM* provides classes and functions designed and implemented with the same naming conventions and functionality than *GLSL* so that anyone who knows *GLSL*, can use *GLM* as well in C++.
This project isn't limited to *GLSL* features. An extension system, based on the *GLSL* extension conventions, provides extended capabilities: matrix transformations, quaternions, data packing, random numbers, noise, etc...
@ -18,11 +18,10 @@ This library works perfectly with *[OpenGL](https://www.opengl.org)* but it also
- Any conform C++98 or C++11 compiler
For more information about *GLM*, please have a look at the [manual](http://glm.g-truc.net/0.9.7/glm-0.9.7.pdf) and the [API reference documentation](http://glm.g-truc.net/0.9.7/api/index.html).
The source code and the documentation are licensed under the [Happy Bunny License (Modified MIT) or the MIT License](./copying.txt).
The source code and the documentation are licensed under both the [Happy Bunny License (Modified MIT) or the MIT License](./copying.txt).
Thanks for contributing to the project by [submitting issues](https://github.com/g-truc/glm/issues) for bug reports and feature requests. Any feedback is welcome at [glm@g-truc.net](mailto://glm@g-truc.net).
```c++
#include <glm/vec3.hpp> // glm::vec3
#include <glm/vec4.hpp> // glm::vec4