mirror of
https://github.com/g-truc/glm.git
synced 2024-11-15 22:34:35 +00:00
123 lines
11 KiB
HTML
123 lines
11 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
|
|
<title>Getting Started</title>
|
||
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Generated by Doxygen 1.7.4 -->
|
||
|
|
<div id="top">
|
||
|
|
<div id="titlearea">
|
||
|
|
<table cellspacing="0" cellpadding="0">
|
||
|
|
<tbody>
|
||
|
|
<tr style="height: 56px;">
|
||
|
|
<td id="projectlogo"><img alt="Logo" src="logo-mini.png"/></td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<div id="navrow1" class="tabs">
|
||
|
|
<ul class="tablist">
|
||
|
|
<li><a href="index.html"><span>Main Page</span></a></li>
|
||
|
|
<li><a href="modules.html"><span>Modules</span></a></li>
|
||
|
|
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
|
||
|
|
<li><a href="annotated.html"><span>Classes</span></a></li>
|
||
|
|
<li><a href="files.html"><span>Files</span></a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div id="nav-path" class="navpath">
|
||
|
|
<ul>
|
||
|
|
<li class="navelem"><a class="el" href="index.html">OpenGL Mathematics</a> </li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="header">
|
||
|
|
<div class="headertitle">
|
||
|
|
<div class="title">Getting Started </div> </div>
|
||
|
|
</div>
|
||
|
|
<div class="contents">
|
||
|
|
<div class="textblock"><h2><a class="anchor" id="started_compiler"></a>
|
||
|
|
Compiler Setup</h2>
|
||
|
|
<p>GLM is a header only library, there is nothing to build to use it which increases its cross platform capabilities.</p>
|
||
|
|
<p>To use GLM, a programmer only has to include <<a class="el" href="a00052_source.html">glm/glm.hpp</a>>. This provides all the GLSL features implemented by GLM.</p>
|
||
|
|
<p>GLM makes heavy usages of C++ templates. This design may significantly increase the compile time for files that use GLM. Precompiled headers are recommended to avoid this issue.</p>
|
||
|
|
<h2><a class="anchor" id="started_sample"></a>
|
||
|
|
Use Sample of GLM</h2>
|
||
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <glm/glm.hpp></span>
|
||
|
|
|
||
|
|
<span class="keywordtype">int</span> foo()
|
||
|
|
{
|
||
|
|
<a class="code" href="a00022.html" title="Basic 4D vector type.">glm::vec4</a> Position = <a class="code" href="a00235.html#ga8fad5ffc01ba6dea689f2a38bf30bda4" title="4 components vector of floating-point numbers.">glm::vec4</a>(<a class="code" href="a00021.html" title="Basic 3D vector type.">glm::vec3</a>(0.0), 1.0);
|
||
|
|
<a class="code" href="a00018.html" title="Template for 4 * 4 matrix of floating-point numbers.">glm::mat4</a> Model = <a class="code" href="a00235.html#gade0eb47c01f79384a6f38017ede17446" title="4 columns of 4 components matrix of floating-point numbers.">glm::mat4</a>(1.0);
|
||
|
|
Model[4] = <a class="code" href="a00235.html#ga8fad5ffc01ba6dea689f2a38bf30bda4" title="4 components vector of floating-point numbers.">glm::vec4</a>(1.0, 1.0, 0.0, 1.0);
|
||
|
|
<a class="code" href="a00022.html" title="Basic 4D vector type.">glm::vec4</a> Transformed = Model * Position;
|
||
|
|
<span class="keywordflow">return</span> 0;
|
||
|
|
}
|
||
|
|
</pre></div><h2><a class="anchor" id="started_structure"></a>
|
||
|
|
Library Structure</h2>
|
||
|
|
<p>GLM is arranged in 2 distinct segments. These are the GLM features based on the GLSL specification and a set of extensions. Some extensions are stable and backward compatible (<a class="el" href="a00239.html">GTC Extensions (Stable)</a> GTC <a class="el" href="a00303.html">VIRTREV Extensions</a> VIRTREV) but some are experimental (<a class="el" href="a00248.html">GTX Extensions (Experimental)</a> GTX) which means that they are not guarantee to be backward compatible from version to version.</p>
|
||
|
|
<p>The <a class="el" href="a00234.html">GLM</a> represents only what GLSL's core provides in terms of types and functions (to the best of GLM's ability to replicate them). All that is needed to use the core is to include <code><<a class="el" href="a00052_source.html">glm/glm.hpp</a>></code>.</p>
|
||
|
|
<p><a class="el" href="a00239.html">GTC extensions</a> are functions and types that add onto the core. These are considered reasonably stable, with their APIs not changing much between versions. Each core extension is included with a separated header file include. All of the core extensions are in the "glm/gtc" directory.</p>
|
||
|
|
<p><a class="el" href="a00248.html">GTX extensions</a> are functions and types that add onto the core. Unlike GTC extensions, their APIs are not considered particularly stable, which is why they are marked "experimental". Like GTC extensions, each experimental extension is included with a separate header file.</p>
|
||
|
|
<p>All the extensions can be included at once by default by including <code><<a class="el" href="a00037_source.html">glm/ext.hpp</a>></code> but this is not recommanded as it will reduce compilation speed for many unused features.</p>
|
||
|
|
<p>All of GLM is defined as direct children of the glm namespace, including extensions.</p>
|
||
|
|
<p>To use a particular extension, simply include the extension header file. All extension features are added to the glm namespace automatically.</p>
|
||
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <glm/glm.hpp></span>
|
||
|
|
<span class="preprocessor">#include <glm/gtc/matrix_transform.hpp></span>
|
||
|
|
|
||
|
|
<span class="keywordtype">int</span> foo()
|
||
|
|
{
|
||
|
|
<a class="code" href="a00022.html" title="Basic 4D vector type.">glm::vec4</a> Position = <a class="code" href="a00235.html#ga8fad5ffc01ba6dea689f2a38bf30bda4" title="4 components vector of floating-point numbers.">glm::vec4</a>(<a class="code" href="a00021.html" title="Basic 3D vector type.">glm::vec3</a>(0.0f), 1.0f);
|
||
|
|
<a class="code" href="a00018.html" title="Template for 4 * 4 matrix of floating-point numbers.">glm::mat4</a> Model = <a class="code" href="a00244.html#ga4683c446c8432476750ade56f2537397" title="Builds a translation 4 * 4 matrix created from a vector of 3 components.">glm::translate</a>(
|
||
|
|
<a class="code" href="a00018.html" title="Template for 4 * 4 matrix of floating-point numbers.">glm::mat4</a>(1.0f), <a class="code" href="a00021.html" title="Basic 3D vector type.">glm::vec3</a>(1.0f));
|
||
|
|
<a class="code" href="a00022.html" title="Basic 4D vector type.">glm::vec4</a> Transformed = Model * Position;
|
||
|
|
<span class="keywordflow">return</span> 0;
|
||
|
|
}
|
||
|
|
</pre></div><h2><a class="anchor" id="started_dependencies"></a>
|
||
|
|
Dependencies</h2>
|
||
|
|
<p>When <<a class="el" href="a00052_source.html">glm/glm.hpp</a>> is included, GLM provides all the GLSL features it implements in C++.</p>
|
||
|
|
<p>When an extension is included, all the dependent extensions will be included as well. All the extensions depend on GLM core. (<<a class="el" href="a00052_source.html">glm/glm.hpp</a>>)</p>
|
||
|
|
<p>There is no dependence with external libraries or external headers like gl.h, gl3.h, glu.h or windows.h. However, if <boost/static_assert.hpp> is included, Boost static assert will be used throughout GLM code to provide compiled time errors.</p>
|
||
|
|
<h2><a class="anchor" id="started_interop"></a>
|
||
|
|
OpenGL Interoperability</h2>
|
||
|
|
<p>It is often useful to get a vector type as an array of its base type. For example, the OpenGL function <code>glUniform3fv()</code> takes an array instead of 3 individual values. If the vector and matrix types were simple arrays, then one could pass them to the function like so: <code>glUniform3fv(loc, 1, glm::vec3(0))</code>. However, this is not the case; the vector and matrix types are C++ classes, not arrays.</p>
|
||
|
|
<p>Instead, GLM provides a mechanism to get the content of a vector or matrix as an array pointer. The <a class="el" href="a00247.html">GLM_GTC_type_ptr: Memory layout access.</a> extension provides this ability.</p>
|
||
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <glm/glm.hpp></span>
|
||
|
|
<span class="preprocessor">#include <glm/gtc/type_ptr.hpp></span>
|
||
|
|
|
||
|
|
<span class="keywordtype">void</span> BindUniforms(GLuint uniVec, GLuint uniMat)
|
||
|
|
{
|
||
|
|
<a class="code" href="a00022.html" title="Basic 4D vector type.">glm::vec4</a> v(0.0f);
|
||
|
|
<a class="code" href="a00018.html" title="Template for 4 * 4 matrix of floating-point numbers.">glm::mat4</a> m(1.0f);
|
||
|
|
...
|
||
|
|
glUniform3fv(uniVec, 1, <a class="code" href="a00247.html#gac21518f95a134dbe3c61460c89264b08" title="Get the const address of the vector content.">glm::value_ptr</a>(v));
|
||
|
|
glUniformMatrix4fv(uniMat, 1, GL_FALSE, <a class="code" href="a00247.html#gac21518f95a134dbe3c61460c89264b08" title="Get the const address of the vector content.">glm::value_ptr</a>(m));
|
||
|
|
}
|
||
|
|
</pre></div><p>Notice that all matrix types are <em>column-major</em> rather than row-major. Hence the need to pass GL_FALSE to glUniformMatrix4fv.</p>
|
||
|
|
<p>Alternatively, the first element of the type can be dereferenced.</p>
|
||
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <glm/glm.hpp></span>
|
||
|
|
|
||
|
|
<span class="keywordtype">void</span> BindUniforms(GLuint uniVec, GLuint uniMat)
|
||
|
|
{
|
||
|
|
<a class="code" href="a00022.html" title="Basic 4D vector type.">glm::vec4</a> v(0.0f);
|
||
|
|
<a class="code" href="a00018.html" title="Template for 4 * 4 matrix of floating-point numbers.">glm::mat4</a> m(1.0f);
|
||
|
|
...
|
||
|
|
glUniform3fv(uniVec, 1, <a class="code" href="a00247.html#gac21518f95a134dbe3c61460c89264b08" title="Get the const address of the vector content.">glm::value_ptr</a>(&v[0]));
|
||
|
|
glUniformMatrix4fv(uniMat, 1, GL_FALSE, &m[0][0]);
|
||
|
|
}
|
||
|
|
</pre></div><p>This method requires dereferencing the very first basic type of the object, not merely the first element. The [] operator on the matrix type returns a column vector; one must then access the first element of that column vector to get a pointer to the basic type.</p>
|
||
|
|
<dl class="note"><dt><b>Note:</b></dt><dd>This operation could have been built into the base vector and matrix types and performed with a cast operator. However, this has some downsides. Implicit casts can cause unexpected and unwanted behavior.</dd></dl>
|
||
|
|
<h2><a class="anchor" id="started_cuda"></a>
|
||
|
|
GLM for CUDA</h2>
|
||
|
|
<p>GLM 0.9.2 introduces CUDA compiler support allowing programmer to use GLM inside a CUDA Kernel. To make GLM compatible with CUDA, GLM_FORCE_CUDA requires to be define before any inclusion of <code><<a class="el" href="a00052_source.html">glm/glm.hpp</a>></code>.</p>
|
||
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor">#define GLM_FORCE_CUDA</span>
|
||
|
|
<span class="preprocessor">#include <glm/glm.hpp></span>
|
||
|
|
</pre></div> </div></div>
|
||
|
|
<hr class="footer"/><address class="footer"><small>Generated by 
|
||
|
|
<a href="http://www.doxygen.org/index.html">
|
||
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
|
||
|
|
</body>
|
||
|
|
</html>
|