1 /// @ref gtc_matrix_transform 2 /// @file glm/gtc/matrix_transform.hpp 3 /// 4 /// @see core (dependence) 5 /// @see gtx_transform 6 /// @see gtx_transform2 7 /// 8 /// @defgroup gtc_matrix_transform GLM_GTC_matrix_transform 9 /// @ingroup gtc 10 /// 11 /// @brief Defines functions that generate common transformation matrices. 12 /// 13 /// The matrices generated by this extension use standard OpenGL fixed-function 14 /// conventions. For example, the lookAt function generates a transform from world 15 /// space into the specific eye space that the projective matrix functions 16 /// (perspective, ortho, etc) are designed to expect. The OpenGL compatibility 17 /// specifications defines the particular layout of this eye space. 18 /// 19 /// <glm/gtc/matrix_transform.hpp> need to be included to use these functionalities. 20 21 #pragma once 22 23 // Dependencies 24 #include "../mat4x4.hpp" 25 #include "../vec2.hpp" 26 #include "../vec3.hpp" 27 #include "../vec4.hpp" 28 #include "../gtc/constants.hpp" 29 30 #if GLM_MESSAGES == GLM_MESSAGES_ENABLED && !defined(GLM_EXT_INCLUDED) 31 # pragma message("GLM: GLM_GTC_matrix_transform extension included") 32 #endif 33 34 namespace glm 35 { 36 /// @addtogroup gtc_matrix_transform 37 /// @{ 38 39 /// Builds a translation 4 * 4 matrix created from a vector of 3 components. 40 /// 41 /// @param m Input matrix multiplied by this translation matrix. 42 /// @param v Coordinates of a translation vector. 43 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 44 /// @code 45 /// #include <glm/glm.hpp> 46 /// #include <glm/gtc/matrix_transform.hpp> 47 /// ... 48 /// glm::mat4 m = glm::translate(glm::mat4(1.0f), glm::vec3(1.0f)); 49 /// // m[0][0] == 1.0f, m[0][1] == 0.0f, m[0][2] == 0.0f, m[0][3] == 0.0f 50 /// // m[1][0] == 0.0f, m[1][1] == 1.0f, m[1][2] == 0.0f, m[1][3] == 0.0f 51 /// // m[2][0] == 0.0f, m[2][1] == 0.0f, m[2][2] == 1.0f, m[2][3] == 0.0f 52 /// // m[3][0] == 1.0f, m[3][1] == 1.0f, m[3][2] == 1.0f, m[3][3] == 1.0f 53 /// @endcode 54 /// @see gtc_matrix_transform 55 /// @see - translate(tmat4x4<T, P> const & m, T x, T y, T z) 56 /// @see - translate(tvec3<T, P> const & v) 57 template <typename T, precision P> 58 GLM_FUNC_DECL tmat4x4<T, P> translate( 59 tmat4x4<T, P> const & m, 60 tvec3<T, P> const & v); 61 62 /// Builds a rotation 4 * 4 matrix created from an axis vector and an angle. 63 /// 64 /// @param m Input matrix multiplied by this rotation matrix. 65 /// @param angle Rotation angle expressed in radians. 66 /// @param axis Rotation axis, recommended to be normalized. 67 /// @tparam T Value type used to build the matrix. Supported: half, float or double. 68 /// @see gtc_matrix_transform 69 /// @see - rotate(tmat4x4<T, P> const & m, T angle, T x, T y, T z) 70 /// @see - rotate(T angle, tvec3<T, P> const & v) 71 template <typename T, precision P> 72 GLM_FUNC_DECL tmat4x4<T, P> rotate( 73 tmat4x4<T, P> const & m, 74 T angle, 75 tvec3<T, P> const & axis); 76 77 /// Builds a scale 4 * 4 matrix created from 3 scalars. 78 /// 79 /// @param m Input matrix multiplied by this scale matrix. 80 /// @param v Ratio of scaling for each axis. 81 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 82 /// @see gtc_matrix_transform 83 /// @see - scale(tmat4x4<T, P> const & m, T x, T y, T z) 84 /// @see - scale(tvec3<T, P> const & v) 85 template <typename T, precision P> 86 GLM_FUNC_DECL tmat4x4<T, P> scale( 87 tmat4x4<T, P> const & m, 88 tvec3<T, P> const & v); 89 90 /// Creates a matrix for an orthographic parallel viewing volume, using the default handedness. 91 /// 92 /// @param left 93 /// @param right 94 /// @param bottom 95 /// @param top 96 /// @param zNear 97 /// @param zFar 98 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 99 /// @see gtc_matrix_transform 100 /// @see - glm::ortho(T const & left, T const & right, T const & bottom, T const & top) 101 template <typename T> 102 GLM_FUNC_DECL tmat4x4<T, defaultp> ortho( 103 T left, 104 T right, 105 T bottom, 106 T top, 107 T zNear, 108 T zFar); 109 110 /// Creates a matrix for an orthographic parallel viewing volume, using left-handedness. 111 /// 112 /// @param left 113 /// @param right 114 /// @param bottom 115 /// @param top 116 /// @param zNear 117 /// @param zFar 118 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 119 /// @see gtc_matrix_transform 120 /// @see - glm::ortho(T const & left, T const & right, T const & bottom, T const & top) 121 template <typename T> 122 GLM_FUNC_DECL tmat4x4<T, defaultp> orthoLH( 123 T left, 124 T right, 125 T bottom, 126 T top, 127 T zNear, 128 T zFar); 129 130 /// Creates a matrix for an orthographic parallel viewing volume, using right-handedness. 131 /// 132 /// @param left 133 /// @param right 134 /// @param bottom 135 /// @param top 136 /// @param zNear 137 /// @param zFar 138 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 139 /// @see gtc_matrix_transform 140 /// @see - glm::ortho(T const & left, T const & right, T const & bottom, T const & top) 141 template <typename T> 142 GLM_FUNC_DECL tmat4x4<T, defaultp> orthoRH( 143 T left, 144 T right, 145 T bottom, 146 T top, 147 T zNear, 148 T zFar); 149 150 /// Creates a matrix for projecting two-dimensional coordinates onto the screen. 151 /// 152 /// @param left 153 /// @param right 154 /// @param bottom 155 /// @param top 156 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 157 /// @see gtc_matrix_transform 158 /// @see - glm::ortho(T const & left, T const & right, T const & bottom, T const & top, T const & zNear, T const & zFar) 159 template <typename T> 160 GLM_FUNC_DECL tmat4x4<T, defaultp> ortho( 161 T left, 162 T right, 163 T bottom, 164 T top); 165 166 /// Creates a frustum matrix with default handedness. 167 /// 168 /// @param left 169 /// @param right 170 /// @param bottom 171 /// @param top 172 /// @param near 173 /// @param far 174 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 175 /// @see gtc_matrix_transform 176 template <typename T> 177 GLM_FUNC_DECL tmat4x4<T, defaultp> frustum( 178 T left, 179 T right, 180 T bottom, 181 T top, 182 T near, 183 T far); 184 185 /// Creates a left handed frustum matrix. 186 /// 187 /// @param left 188 /// @param right 189 /// @param bottom 190 /// @param top 191 /// @param near 192 /// @param far 193 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 194 /// @see gtc_matrix_transform 195 template <typename T> 196 GLM_FUNC_DECL tmat4x4<T, defaultp> frustumLH( 197 T left, 198 T right, 199 T bottom, 200 T top, 201 T near, 202 T far); 203 204 /// Creates a right handed frustum matrix. 205 /// 206 /// @param left 207 /// @param right 208 /// @param bottom 209 /// @param top 210 /// @param near 211 /// @param far 212 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 213 /// @see gtc_matrix_transform 214 template <typename T> 215 GLM_FUNC_DECL tmat4x4<T, defaultp> frustumRH( 216 T left, 217 T right, 218 T bottom, 219 T top, 220 T near, 221 T far); 222 223 /// Creates a matrix for a symetric perspective-view frustum based on the default handedness. 224 /// 225 /// @param fovy Specifies the field of view angle in the y direction. Expressed in radians. 226 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 227 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 228 /// @param far Specifies the distance from the viewer to the far clipping plane (always positive). 229 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 230 /// @see gtc_matrix_transform 231 template <typename T> 232 GLM_FUNC_DECL tmat4x4<T, defaultp> perspective( 233 T fovy, 234 T aspect, 235 T near, 236 T far); 237 238 /// Creates a matrix for a right handed, symetric perspective-view frustum. 239 /// 240 /// @param fovy Specifies the field of view angle, in degrees, in the y direction. Expressed in radians. 241 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 242 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 243 /// @param far Specifies the distance from the viewer to the far clipping plane (always positive). 244 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 245 /// @see gtc_matrix_transform 246 template <typename T> 247 GLM_FUNC_DECL tmat4x4<T, defaultp> perspectiveRH( 248 T fovy, 249 T aspect, 250 T near, 251 T far); 252 253 /// Creates a matrix for a left handed, symetric perspective-view frustum. 254 /// 255 /// @param fovy Specifies the field of view angle, in degrees, in the y direction. Expressed in radians. 256 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 257 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 258 /// @param far Specifies the distance from the viewer to the far clipping plane (always positive). 259 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 260 /// @see gtc_matrix_transform 261 template <typename T> 262 GLM_FUNC_DECL tmat4x4<T, defaultp> perspectiveLH( 263 T fovy, 264 T aspect, 265 T near, 266 T far); 267 268 /// Builds a perspective projection matrix based on a field of view and the default handedness. 269 /// 270 /// @param fov Expressed in radians. 271 /// @param width 272 /// @param height 273 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 274 /// @param far Specifies the distance from the viewer to the far clipping plane (always positive). 275 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 276 /// @see gtc_matrix_transform 277 template <typename T> 278 GLM_FUNC_DECL tmat4x4<T, defaultp> perspectiveFov( 279 T fov, 280 T width, 281 T height, 282 T near, 283 T far); 284 285 /// Builds a right handed perspective projection matrix based on a field of view. 286 /// 287 /// @param fov Expressed in radians. 288 /// @param width 289 /// @param height 290 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 291 /// @param far Specifies the distance from the viewer to the far clipping plane (always positive). 292 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 293 /// @see gtc_matrix_transform 294 template <typename T> 295 GLM_FUNC_DECL tmat4x4<T, defaultp> perspectiveFovRH( 296 T fov, 297 T width, 298 T height, 299 T near, 300 T far); 301 302 /// Builds a left handed perspective projection matrix based on a field of view. 303 /// 304 /// @param fov Expressed in radians. 305 /// @param width 306 /// @param height 307 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 308 /// @param far Specifies the distance from the viewer to the far clipping plane (always positive). 309 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 310 /// @see gtc_matrix_transform 311 template <typename T> 312 GLM_FUNC_DECL tmat4x4<T, defaultp> perspectiveFovLH( 313 T fov, 314 T width, 315 T height, 316 T near, 317 T far); 318 319 /// Creates a matrix for a symmetric perspective-view frustum with far plane at infinite with default handedness. 320 /// 321 /// @param fovy Specifies the field of view angle, in degrees, in the y direction. Expressed in radians. 322 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 323 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 324 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 325 /// @see gtc_matrix_transform 326 template <typename T> 327 GLM_FUNC_DECL tmat4x4<T, defaultp> infinitePerspective( 328 T fovy, T aspect, T near); 329 330 /// Creates a matrix for a left handed, symmetric perspective-view frustum with far plane at infinite. 331 /// 332 /// @param fovy Specifies the field of view angle, in degrees, in the y direction. Expressed in radians. 333 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 334 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 335 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 336 /// @see gtc_matrix_transform 337 template <typename T> 338 GLM_FUNC_DECL tmat4x4<T, defaultp> infinitePerspectiveLH( 339 T fovy, T aspect, T near); 340 341 /// Creates a matrix for a right handed, symmetric perspective-view frustum with far plane at infinite. 342 /// 343 /// @param fovy Specifies the field of view angle, in degrees, in the y direction. Expressed in radians. 344 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 345 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 346 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 347 /// @see gtc_matrix_transform 348 template <typename T> 349 GLM_FUNC_DECL tmat4x4<T, defaultp> infinitePerspectiveRH( 350 T fovy, T aspect, T near); 351 352 /// Creates a matrix for a symmetric perspective-view frustum with far plane at infinite for graphics hardware that doesn't support depth clamping. 353 /// 354 /// @param fovy Specifies the field of view angle, in degrees, in the y direction. Expressed in radians. 355 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 356 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 357 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 358 /// @see gtc_matrix_transform 359 template <typename T> 360 GLM_FUNC_DECL tmat4x4<T, defaultp> tweakedInfinitePerspective( 361 T fovy, T aspect, T near); 362 363 /// Creates a matrix for a symmetric perspective-view frustum with far plane at infinite for graphics hardware that doesn't support depth clamping. 364 /// 365 /// @param fovy Specifies the field of view angle, in degrees, in the y direction. Expressed in radians. 366 /// @param aspect Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height). 367 /// @param near Specifies the distance from the viewer to the near clipping plane (always positive). 368 /// @param ep 369 /// @tparam T Value type used to build the matrix. Currently supported: half (not recommanded), float or double. 370 /// @see gtc_matrix_transform 371 template <typename T> 372 GLM_FUNC_DECL tmat4x4<T, defaultp> tweakedInfinitePerspective( 373 T fovy, T aspect, T near, T ep); 374 375 /// Map the specified object coordinates (obj.x, obj.y, obj.z) into window coordinates. 376 /// 377 /// @param obj Specify the object coordinates. 378 /// @param model Specifies the current modelview matrix 379 /// @param proj Specifies the current projection matrix 380 /// @param viewport Specifies the current viewport 381 /// @return Return the computed window coordinates. 382 /// @tparam T Native type used for the computation. Currently supported: half (not recommanded), float or double. 383 /// @tparam U Currently supported: Floating-point types and integer types. 384 /// @see gtc_matrix_transform 385 template <typename T, typename U, precision P> 386 GLM_FUNC_DECL tvec3<T, P> project( 387 tvec3<T, P> const & obj, 388 tmat4x4<T, P> const & model, 389 tmat4x4<T, P> const & proj, 390 tvec4<U, P> const & viewport); 391 392 /// Map the specified window coordinates (win.x, win.y, win.z) into object coordinates. 393 /// 394 /// @param win Specify the window coordinates to be mapped. 395 /// @param model Specifies the modelview matrix 396 /// @param proj Specifies the projection matrix 397 /// @param viewport Specifies the viewport 398 /// @return Returns the computed object coordinates. 399 /// @tparam T Native type used for the computation. Currently supported: half (not recommanded), float or double. 400 /// @tparam U Currently supported: Floating-point types and integer types. 401 /// @see gtc_matrix_transform 402 template <typename T, typename U, precision P> 403 GLM_FUNC_DECL tvec3<T, P> unProject( 404 tvec3<T, P> const & win, 405 tmat4x4<T, P> const & model, 406 tmat4x4<T, P> const & proj, 407 tvec4<U, P> const & viewport); 408 409 /// Define a picking region 410 /// 411 /// @param center 412 /// @param delta 413 /// @param viewport 414 /// @tparam T Native type used for the computation. Currently supported: half (not recommanded), float or double. 415 /// @tparam U Currently supported: Floating-point types and integer types. 416 /// @see gtc_matrix_transform 417 template <typename T, precision P, typename U> 418 GLM_FUNC_DECL tmat4x4<T, P> pickMatrix( 419 tvec2<T, P> const & center, 420 tvec2<T, P> const & delta, 421 tvec4<U, P> const & viewport); 422 423 /// Build a look at view matrix based on the default handedness. 424 /// 425 /// @param eye Position of the camera 426 /// @param center Position where the camera is looking at 427 /// @param up Normalized up vector, how the camera is oriented. Typically (0, 0, 1) 428 /// @see gtc_matrix_transform 429 /// @see - frustum(T const & left, T const & right, T const & bottom, T const & top, T const & nearVal, T const & farVal) frustum(T const & left, T const & right, T const & bottom, T const & top, T const & nearVal, T const & farVal) 430 template <typename T, precision P> 431 GLM_FUNC_DECL tmat4x4<T, P> lookAt( 432 tvec3<T, P> const & eye, 433 tvec3<T, P> const & center, 434 tvec3<T, P> const & up); 435 436 /// Build a right handed look at view matrix. 437 /// 438 /// @param eye Position of the camera 439 /// @param center Position where the camera is looking at 440 /// @param up Normalized up vector, how the camera is oriented. Typically (0, 0, 1) 441 /// @see gtc_matrix_transform 442 /// @see - frustum(T const & left, T const & right, T const & bottom, T const & top, T const & nearVal, T const & farVal) frustum(T const & left, T const & right, T const & bottom, T const & top, T const & nearVal, T const & farVal) 443 template <typename T, precision P> 444 GLM_FUNC_DECL tmat4x4<T, P> lookAtRH( 445 tvec3<T, P> const & eye, 446 tvec3<T, P> const & center, 447 tvec3<T, P> const & up); 448 449 /// Build a left handed look at view matrix. 450 /// 451 /// @param eye Position of the camera 452 /// @param center Position where the camera is looking at 453 /// @param up Normalized up vector, how the camera is oriented. Typically (0, 0, 1) 454 /// @see gtc_matrix_transform 455 /// @see - frustum(T const & left, T const & right, T const & bottom, T const & top, T const & nearVal, T const & farVal) frustum(T const & left, T const & right, T const & bottom, T const & top, T const & nearVal, T const & farVal) 456 template <typename T, precision P> 457 GLM_FUNC_DECL tmat4x4<T, P> lookAtLH( 458 tvec3<T, P> const & eye, 459 tvec3<T, P> const & center, 460 tvec3<T, P> const & up); 461 462 /// @} 463 }//namespace glm 464 465 #include "matrix_transform.inl" 466