From a672f612ad06e634063703536a299cceecb9c407 Mon Sep 17 00:00:00 2001 From: Christophe Riccio Date: Tue, 7 Jun 2011 16:37:57 +0100 Subject: [PATCH] Moved docygen documentation to each extension file and added missing extension documentation --- doc/gtcModules.doxy | 108 --------------------------------- doc/gtxModules.doxy | 4 +- glm/ext.hpp | 45 +++++++++++--- glm/glm.hpp | 34 +---------- glm/gtc/half_float.hpp | 9 ++- glm/gtc/matrix_access.hpp | 6 ++ glm/gtc/matrix_integer.hpp | 6 ++ glm/gtc/matrix_inverse.hpp | 10 ++- glm/gtc/matrix_transform.hpp | 17 +++++- glm/gtc/quaternion.hpp | 11 +++- glm/gtc/swizzle.hpp | 11 ++++ glm/gtc/type_precision.hpp | 10 +++ glm/gtc/type_ptr.hpp | 29 ++++++++- glm/gtx/associated_min_max.hpp | 8 ++- glm/gtx/noise.hpp | 57 ++++++++++++----- 15 files changed, 191 insertions(+), 174 deletions(-) diff --git a/doc/gtcModules.doxy b/doc/gtcModules.doxy index b6e53fd8..e69de29b 100644 --- a/doc/gtcModules.doxy +++ b/doc/gtcModules.doxy @@ -1,108 +0,0 @@ -/*! - \defgroup gtc GTC Extensions (Stable) - - \brief Functions and types that the GLSL specification doesn't define, but useful to have for a C++ program. - - GTC extensions aim to be stable. - - Even if it's highly unrecommended, it's possible to include all the extensions at once by - including . Otherwise, each extension needs to be included a specific file. -**/ - -/*! - \defgroup gtc_half_float GLM_GTC_half_float: Half-precision floating-point based types and functions - \ingroup gtc - - Defines the half-precision floating-point type, along with various typedefs for vectors and matrices. - need to be included to use these functionalities. -**/ - -/*! - \defgroup gtc_matrix_access GLM_GTC_matrix_access: Access matrix rows and columns - \ingroup gtc - - Defines functions to access rows or columns of a matrix easily. - need to be included to use these functionalities. -**/ - -/*! - \defgroup gtc_matrix_integer GLM_GTC_matrix_integer: Integer matrix types - \ingroup gtc - - Defines a number of matrices with integer types. - need to be included to use these functionalities. -**/ - -/*! - \defgroup gtc_matrix_inverse GLM_GTC_matrix_inverse: Additional matrix inverse function - \ingroup gtc - - Defines additional matrix inverting functions. - need to be included to use these functionalities. -**/ - -/*! - \defgroup gtc_matrix_transform GLM_GTC_matrix_transform: Matrix transform functions - \ingroup gtc - - \brief Defines functions that generate common transformation 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 defines the particular layout of this eye space. - - need to be included to use these functionalities. -**/ - -/*! - \defgroup gtc_quaternion GLM_GTC_quaternion: Quaternion types and functions - \ingroup gtc - - \brief Defines a templated quaternion type and several quaternion operations. - - need to be included to use these functionalities. -**/ - -/*! - \defgroup gtc_type_precision GLM_GTC_type_precision: Vector and matrix types with defined precisions - \ingroup gtc - - \brief Defines specific C++-based precision types. - - \ref core_precision defines types based on GLSL's precision qualifiers. This - extension defines types based on explicitly-sized C++ data types. - - need to be included to use these functionalities. -**/ - -/*! - \defgroup gtc_type_ptr GLM_GTC_type_ptr: Memory layout access - \ingroup gtc - - \brief Used to get a pointer to the memory layout of a basic type. - - This extension defines an overloaded function, glm::value_ptr, which - takes any of the \ref core_template "core template types". 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. - - Example: - - \code -#include -#include - -glm::vec3 aVector(3); -glm::mat4 someMatrix(1.0); - -glUniform3fv(uniformLoc, 1, glm::value_ptr(aVector)); -glUniformMatrix4fv(uniformMatrixLoc, 1, GL_FALSE, glm::value_ptr(someMatrix)); - \endcode - - need to be included to use these functionalities. -**/ - diff --git a/doc/gtxModules.doxy b/doc/gtxModules.doxy index d585cf8b..34353502 100644 --- a/doc/gtxModules.doxy +++ b/doc/gtxModules.doxy @@ -11,13 +11,13 @@ including . Otherwise, each extension needs to be included a specific file. **/ -/*! +/* \defgroup gtx_associated_min_max GLM_GTX_associated_min_max: Associated Min/Max \ingroup gtx \brief Min and max functions that return associated values not the compared onces. need to be included to use these functionalities. -**/ +*/ /*! \defgroup gtx_bit GLM_GTX_bit: Extended bitwise operations diff --git a/glm/ext.hpp b/glm/ext.hpp index d925fe6f..88277f3e 100644 --- a/glm/ext.hpp +++ b/glm/ext.hpp @@ -1,11 +1,40 @@ -/////////////////////////////////////////////////////////////////////////////////////////////////// -// OpenGL Mathematics Copyright (c) 2005 - 2011 G-Truc Creation (www.g-truc.net) -/////////////////////////////////////////////////////////////////////////////////////////////////// -// Created : 2009-05-01 -// Updated : 2010-12-13 -// Licence : This source is under MIT License -// File : glm/ext.hpp -/////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////// +/// OpenGL Mathematics (glm.g-truc.net) +/// +/// Copyright (c) 2005 - 2011 G-Truc Creation (www.g-truc.net) +/// Permission is hereby granted, free of charge, to any person obtaining a copy +/// of this software and associated documentation files (the "Software"), to deal +/// in the Software without restriction, including without limitation the rights +/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +/// copies of the Software, and to permit persons to whom the Software is +/// furnished to do so, subject to the following conditions: +/// +/// The above copyright notice and this permission notice shall be included in +/// all copies or substantial portions of the Software. +/// +/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +/// THE SOFTWARE. +/// +/// @file glm/glm.hpp +/// @date 2009-05-01 / 2011-05-16 +/// @author Christophe Riccio +/// +/// @ref core (Dependence) +/// +/// @defgroup gtc GTC Extensions (Stable) +/// +/// @brief Functions and types that the GLSL specification doesn't define, but useful to have for a C++ program. +/// +/// GTC extensions aim to be stable. +/// +/// Even if it's highly unrecommended, it's possible to include all the extensions at once by +/// including . Otherwise, each extension needs to be included a specific file. +/////////////////////////////////////////////////////////////////////////////////// #ifndef glm_ext #define glm_ext diff --git a/glm/glm.hpp b/glm/glm.hpp index 1fb994b6..fa45aace 100644 --- a/glm/glm.hpp +++ b/glm/glm.hpp @@ -43,42 +43,14 @@ # pragma message("GLM: Core library included") #endif//GLM_MESSAGE -//! GLM namespace, it contains all GLSL based features. namespace glm { - //! GLM core. Namespace that includes all the feature define by GLSL 4.10.6 specification. This namespace is included in glm namespace. - namespace core - { - //! Scalar, vectors and matrices - //! from section 4.1.2 Booleans, 4.1.3 Integers section, 4.1.4 Floats section, - //! 4.1.5 Vectors and section 4.1.6 Matrices of GLSL 1.30.8 specification. - //! This namespace resolves precision qualifier define in section 4.5 of GLSL 1.30.8 specification. - namespace type - { - namespace precision{} - } - - //! Some of the functions defined in section 8 Built-in Functions of GLSL 1.30.8 specification. - //! Angle and trigonometry, exponential, common, geometric, matrix and vector relational functions. - namespace function{} - }//namespace core - - //! G-Truc Creation stable extensions. namespace gtc{} - - //! G-Truc Creation experimental extensions. - //! The interface could change between releases. namespace gtx{} - - //! VIRTREV extensions. namespace virtrev{} - - using namespace core; - using namespace core::type; - using namespace core::type::precision; - using namespace core::function; - using namespace gtc; - using namespace gtx; + + using namespace gtc; + using namespace gtx; }//namespace glm #include "./core/_detail.hpp" diff --git a/glm/gtc/half_float.hpp b/glm/gtc/half_float.hpp index 2de393d7..1a3a3107 100644 --- a/glm/gtc/half_float.hpp +++ b/glm/gtc/half_float.hpp @@ -26,6 +26,13 @@ /// @author Christophe Riccio /// /// @see core (dependence) +/// +/// @defgroup gtc_half_float GLM_GTC_half_float: Half-precision floating-point based types and functions +/// @ingroup gtc +/// +/// Defines the half-precision floating-point type, along with various typedefs for vectors and matrices. +/// need to be included to use these functionalities. +/// /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_half_float @@ -344,7 +351,7 @@ namespace detail namespace gtc { - /// \addtogroup gtc_half_float + /// @addtogroup gtc_half_float /// @{ /// Type for half-precision floating-point numbers. diff --git a/glm/gtc/matrix_access.hpp b/glm/gtc/matrix_access.hpp index 6a459f24..c7914211 100644 --- a/glm/gtc/matrix_access.hpp +++ b/glm/gtc/matrix_access.hpp @@ -26,6 +26,12 @@ /// @author Christophe Riccio /// /// @see core (dependence) +/// +/// @defgroup gtc_matrix_access GLM_GTC_matrix_access: Access matrix rows and columns +/// @ingroup gtc +/// +/// Defines functions to access rows or columns of a matrix easily. +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_matrix_access diff --git a/glm/gtc/matrix_integer.hpp b/glm/gtc/matrix_integer.hpp index de480b60..48246817 100644 --- a/glm/gtc/matrix_integer.hpp +++ b/glm/gtc/matrix_integer.hpp @@ -26,6 +26,12 @@ /// @author Christophe Riccio /// /// @see core (dependence) +/// +/// @defgroup gtc_matrix_integer GLM_GTC_matrix_integer: Integer matrix types +/// @ingroup gtc +/// +/// Defines a number of matrices with integer types. +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_matrix_integer diff --git a/glm/gtc/matrix_inverse.hpp b/glm/gtc/matrix_inverse.hpp index 16b2e3ed..b130284f 100644 --- a/glm/gtc/matrix_inverse.hpp +++ b/glm/gtc/matrix_inverse.hpp @@ -26,6 +26,12 @@ /// @author Christophe Riccio /// /// @see core (dependence) +/// +/// @defgroup gtc_matrix_inverse GLM_GTC_matrix_inverse: Additional matrix inverse function +/// @ingroup gtc +/// +/// Defines additional matrix inverting functions. +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_matrix_inverse @@ -39,8 +45,8 @@ #endif namespace glm{ -namespace gtc{ - +namespace gtc +{ /// @addtogroup gtc_matrix_inverse /// @{ diff --git a/glm/gtc/matrix_transform.hpp b/glm/gtc/matrix_transform.hpp index 83fdf7c7..d94f0be3 100644 --- a/glm/gtc/matrix_transform.hpp +++ b/glm/gtc/matrix_transform.hpp @@ -28,6 +28,19 @@ /// @see core (dependence) /// @see gtx_transform /// @see gtx_transform2 +/// +/// @defgroup gtc_matrix_transform GLM_GTC_matrix_transform: Matrix transform functions +/// @ingroup gtc +/// +/// @brief Defines functions that generate common transformation 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 defines the particular layout of this eye space. +/// +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_matrix_transform @@ -41,8 +54,8 @@ #endif namespace glm{ -namespace gtc{ - +namespace gtc +{ /// @addtogroup gtc_matrix_transform /// @{ diff --git a/glm/gtc/quaternion.hpp b/glm/gtc/quaternion.hpp index c2ffbd0f..577b01ef 100644 --- a/glm/gtc/quaternion.hpp +++ b/glm/gtc/quaternion.hpp @@ -30,6 +30,13 @@ /// /// @todo Study constructors with angles and axis /// @todo Study constructors with vec3 that are the imaginary component of quaternion +/// +/// @defgroup gtc_quaternion GLM_GTC_quaternion: Quaternion types and functions +/// @ingroup gtc +/// +/// @brief Defines a templated quaternion type and several quaternion operations. +/// +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_quaternion @@ -46,9 +53,9 @@ namespace glm{ namespace detail { - /// \brief Template for quaternion. + /// @brief Template for quaternion. /// From GLM_GTC_quaternion extension. - /// \ingroup gtc_quaternion + /// @ingroup gtc_quaternion template struct tquat// : public genType { diff --git a/glm/gtc/swizzle.hpp b/glm/gtc/swizzle.hpp index a0c5325c..c58551c1 100644 --- a/glm/gtc/swizzle.hpp +++ b/glm/gtc/swizzle.hpp @@ -26,6 +26,13 @@ /// @author Christophe Riccio /// /// @see core (dependence) +/// +/// @defgroup gtc_swizzle GLM_GTC_swizzle: Swizzle 'operator' implementation +/// @ingroup gtc +/// +/// @brief Provide functions to emulate GLSL swizzle operator fonctionalities. +/// +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_swizzle @@ -42,6 +49,9 @@ namespace glm{ namespace gtc { + /// @addtogroup gtc_half_float + /// @{ + template class vecType> T const & swizzle( vecType const & v, @@ -358,6 +368,7 @@ namespace gtc static_swizzle4_ref(glm::u32, 4) static_swizzle4_ref(glm::u64, 4) + /// @} }//namespace gtc }//namespace glm diff --git a/glm/gtc/type_precision.hpp b/glm/gtc/type_precision.hpp index 6e80bedb..4cfea1dd 100644 --- a/glm/gtc/type_precision.hpp +++ b/glm/gtc/type_precision.hpp @@ -28,6 +28,16 @@ /// @see core (dependence) /// @see gtc_half_float (dependence) /// @see gtc_quaternion (dependence) +/// +/// @defgroup gtc_type_precision GLM_GTC_type_precision: Vector and matrix types with defined precisions +/// @ingroup gtc +/// +/// @brief Defines specific C++-based precision types. +/// +/// @ref core_precision defines types based on GLSL's precision qualifiers. This +/// extension defines types based on explicitly-sized C++ data types. +/// +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_type_precision diff --git a/glm/gtc/type_ptr.hpp b/glm/gtc/type_ptr.hpp index 5849d243..4b12a958 100644 --- a/glm/gtc/type_ptr.hpp +++ b/glm/gtc/type_ptr.hpp @@ -28,6 +28,32 @@ /// @see core (dependence) /// @see gtc_half_float (dependence) /// @see gtc_quaternion (dependence) +/// +/// @defgroup gtc_type_ptr GLM_GTC_type_ptr: Memory layout access +/// @ingroup gtc +/// +/// @brief Used to get a pointer to the memory layout of a basic type. +/// +/// This extension defines an overloaded function, glm::value_ptr, which +/// takes any of the \ref core_template "core template types". 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. +/// +/// Example: +/// @code +/// #include +/// #include +/// +/// glm::vec3 aVector(3); +/// glm::mat4 someMatrix(1.0); +/// +/// glUniform3fv(uniformLoc, 1, glm::value_ptr(aVector)); +/// glUniformMatrix4fv(uniformMatrixLoc, 1, GL_FALSE, glm::value_ptr(someMatrix)); +/// @endcode +/// +/// need to be included to use these functionalities. /////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtc_type_ptr @@ -44,7 +70,8 @@ #endif namespace glm{ -namespace gtc{ +namespace gtc +{ /// @addtogroup gtc_type_ptr /// @{ diff --git a/glm/gtx/associated_min_max.hpp b/glm/gtx/associated_min_max.hpp index 10d2aa2f..ac76fc7f 100644 --- a/glm/gtx/associated_min_max.hpp +++ b/glm/gtx/associated_min_max.hpp @@ -24,7 +24,13 @@ namespace glm{ namespace gtx { - /// \addtogroup gtx_associated_min_max + /// @defgroup gtx_associated_min_max GLM_GTX_associated_min_max: Associated Min/Max + /// @ingroup gtx + /// + /// @brief Min and max functions that return associated values not the compared onces. + /// need to be included to use these functionalities. + /// + /// @addtogroup gtx_associated_min_max /// @{ //! \brief Min comparison between 2 variables diff --git a/glm/gtx/noise.hpp b/glm/gtx/noise.hpp index d4d519f9..da421fa2 100644 --- a/glm/gtx/noise.hpp +++ b/glm/gtx/noise.hpp @@ -1,19 +1,44 @@ -/////////////////////////////////////////////////////////////////////////////////////////////////// -// OpenGL Mathematics Copyright (c) 2005 - 2011 G-Truc Creation (www.g-truc.net) -/////////////////////////////////////////////////////////////////////////////////////////////////// -// Based on the work of Stefan Gustavson and Ashima Arts on "webgl-noise": -// https://github.com/ashima/webgl-noise -// Following Stefan Gustavson's paper "Simplex noise demystified": -// http://www.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf -/////////////////////////////////////////////////////////////////////////////////////////////////// -// Created : 2011-04-21 -// Updated : 2011-04-21 -// Licence : This source is under MIT License -// File : glm/gtx/noise.hpp -/////////////////////////////////////////////////////////////////////////////////////////////////// -// Dependency: -// - GLM core -/////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////// +/// OpenGL Mathematics (glm.g-truc.net) +/// +/// Copyright (c) 2005 - 2011 G-Truc Creation (www.g-truc.net) +/// Permission is hereby granted, free of charge, to any person obtaining a copy +/// of this software and associated documentation files (the "Software"), to deal +/// in the Software without restriction, including without limitation the rights +/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +/// copies of the Software, and to permit persons to whom the Software is +/// furnished to do so, subject to the following conditions: +/// +/// The above copyright notice and this permission notice shall be included in +/// all copies or substantial portions of the Software. +/// +/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +/// THE SOFTWARE. +/// +/// @ref gtx_noise +/// @file glm/gtx/noise.hpp +/// @date 2011-04-21 / 2011-06-07 +/// @author Christophe Riccio +/// +/// @see core (dependence) +/// +/// @defgroup gtx_noise GLM_GTX_noise: Procedural noise functions +/// @ingroup gtx +/// +/// Defines 2D, 3D and 4D procedural noise functions +/// Based on the work of Stefan Gustavson and Ashima Arts on "webgl-noise": +/// https://github.com/ashima/webgl-noise +/// Following Stefan Gustavson's paper "Simplex noise demystified": +/// http://www.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf +/// Defines the half-precision floating-point type, along with various typedefs for vectors and matrices. +/// need to be included to use these functionalities. +/// +/////////////////////////////////////////////////////////////////////////////////// #ifndef glm_gtx_noise #define glm_gtx_noise