docs: add infinite perspective

Implement infinite perspective projection matrix creation functions

docs/source/cam.rst

@@ -36,8 +36,10 @@ Functions:
 #. :c:func:`glm_ortho_default`
 #. :c:func:`glm_ortho_default_s`
 #. :c:func:`glm_perspective`
+#. :c:func:`glm_perspective_infinite`
 #. :c:func:`glm_persp_move_far`
 #. :c:func:`glm_perspective_default`
+#. :c:func:`glm_perspective_default_infinite`
 #. :c:func:`glm_perspective_resize`
 #. :c:func:`glm_lookat`
 #. :c:func:`glm_look`
@@ -146,6 +148,21 @@ Functions documentation
       | *[in]*  **farVal**  far clipping planes
       | *[out]* **dest**    result matrix
 
+.. c:function:: void  glm_perspective_infinite(float fovy, float aspect, float nearZ, mat4 dest)
+
+    | set up perspective projection matrix with infinite far plane
+
+    The far clipping plane is pushed to infinity. This can improve depth
+    precision for distant objects and is required by some rendering techniques
+    such as shadow volumes. Dispatches to the appropriate clipspace variant
+    based on compile-time configuration (LH/RH, NO/ZO).
+
+    Parameters:
+      | *[in]*  **fovy**    field of view angle (in radians)
+      | *[in]*  **aspect**  aspect ratio ( width / height )
+      | *[in]*  **nearZ**   near clipping plane
+      | *[out]* **dest**    result matrix
+
 .. c:function:: void  glm_persp_move_far(mat4 proj, float deltaFar)
 
     | extend perspective projection matrix's far distance
@@ -165,6 +182,20 @@ Functions documentation
       | *[in]*  **aspect** aspect aspect ratio ( width / height )
       | *[out]* **dest**   result matrix
 
+.. c:function:: void glm_perspective_default_infinite(float aspect, mat4 dest)
+
+    | set up infinite perspective projection matrix with default near
+      and angle values
+
+    Equivalent to calling :c:func:`glm_perspective_infinite` with
+    ``fovy = GLM_PI_4`` (45°) and ``nearZ = 0.01``. Useful as a
+    quick drop-in when you need an infinite projection without tuning
+    the individual parameters.
+
+    Parameters:
+      | *[in]*  **aspect** aspect ratio ( width / height )
+      | *[out]* **dest**   result matrix
+
 .. c:function:: void  glm_perspective_resize(float aspect, mat4 proj)
 
     | resize perspective matrix by aspect ratio ( width / height )

include/cglm/call/cam.h

@@ -51,6 +51,10 @@ CGLM_EXPORT
 void
 glmc_perspective(float fovy, float aspect, float nearZ, float farZ, mat4 dest);
 
+CGLM_EXPORT
+void
+glmc_perspective_infinite(float fovy, float aspect, float nearZ, mat4 dest);
+
 CGLM_EXPORT
 void
 glmc_persp_move_far(mat4 proj, float deltaFar);
@@ -59,6 +63,10 @@ CGLM_EXPORT
 void
 glmc_perspective_default(float aspect, mat4 dest);
 
+CGLM_EXPORT
+void
+glmc_perspective_default_infinite(float aspect, mat4 dest);
+
 CGLM_EXPORT
 void
 glmc_perspective_resize(float aspect, mat4 proj);

include/cglm/cam.h

@@ -25,7 +25,12 @@
                                      float nearZ,
                                      float farZ,
                                      mat4  dest)
+   CGLM_INLINE void  glm_perspective_infinite(float fovy,
+                                              float aspect,
+                                              float nearZ,
+                                              mat4  dest)
    CGLM_INLINE void  glm_perspective_default(float aspect, mat4 dest)
+   CGLM_INLINE void  glm_perspective_default_infinite(float aspect, mat4 dest)
    CGLM_INLINE void  glm_perspective_resize(float aspect, mat4 proj)
    CGLM_INLINE void  glm_lookat(vec3 eye, vec3 center, vec3 up, mat4 dest)
    CGLM_INLINE void  glm_look(vec3 eye, vec3 dir, vec3 up, mat4 dest)
@@ -87,7 +92,7 @@
 #endif
 
 /*!
- * @brief set up perspective peprojection matrix
+ * @brief set up perspective projection matrix
  *
  * @param[in]  left    viewport.left
  * @param[in]  right   viewport.right
@@ -274,6 +279,28 @@ glm_perspective(float fovy, float aspect, float nearZ, float farZ, mat4 dest) {
 #endif
 }
 
+/*!
+ * @brief set up perspective projection matrix with infinite far plane
+ *
+ * @param[in]  fovy    field of view angle
+ * @param[in]  aspect  aspect ratio ( width / height )
+ * @param[in]  nearZ   near clipping plane
+ * @param[out] dest    result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_infinite(float fovy, float aspect, float nearZ, mat4 dest) {
+#if CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_LH_ZO
+  glm_perspective_infinite_lh_zo(fovy, aspect, nearZ, dest);
+#elif CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_LH_NO
+  glm_perspective_infinite_lh_no(fovy, aspect, nearZ, dest);
+#elif CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_RH_ZO
+  glm_perspective_infinite_rh_zo(fovy, aspect, nearZ, dest);
+#elif CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_RH_NO
+  glm_perspective_infinite_rh_no(fovy, aspect, nearZ, dest);
+#endif
+}
+
 /*!
  * @brief extend perspective projection matrix's far distance
  *
@@ -317,6 +344,27 @@ glm_perspective_default(float aspect, mat4 dest) {
 #endif
 }
 
+/*!
+ * @brief set up infinite perspective projection matrix with default near
+ *        and angle values
+ *
+ * @param[in]  aspect aspect ratio ( width / height )
+ * @param[out] dest   result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_default_infinite(float aspect, mat4 dest) {
+#if CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_LH_ZO
+  glm_perspective_default_infinite_lh_zo(aspect, dest);
+#elif CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_LH_NO
+  glm_perspective_default_infinite_lh_no(aspect, dest);
+#elif CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_RH_ZO
+  glm_perspective_default_infinite_rh_zo(aspect, dest);
+#elif CGLM_CONFIG_CLIP_CONTROL == CGLM_CLIP_CONTROL_RH_NO
+  glm_perspective_default_infinite_rh_no(aspect, dest);
+#endif
+}
+
 /*!
  * @brief resize perspective matrix by aspect ratio ( width / height )
  *        this makes very easy to resize proj matrix when window /viewport

include/cglm/clipspace/persp_lh_no.h

@@ -16,7 +16,12 @@
                                           float nearZ,
                                           float farZ,
                                           mat4  dest)
+   CGLM_INLINE void glm_perspective_infinite_lh_no(float fovy,
+                                                   float aspect,
+                                                   float nearZ,
+                                                   mat4  dest)
    CGLM_INLINE void glm_perspective_default_lh_no(float aspect, mat4 dest)
+   CGLM_INLINE void glm_perspective_default_infinite_lh_no(float aspect, mat4 dest)
    CGLM_INLINE void glm_perspective_resize_lh_no(float aspect, mat4 proj)
    CGLM_INLINE void glm_persp_move_far_lh_no(mat4 proj,
                                              float deltaFar)
@@ -116,7 +121,35 @@ glm_perspective_lh_no(float fovy,
   dest[2][2] =-(nearZ + farZ) * fn;
   dest[2][3] = 1.0f;
   dest[3][2] = 2.0f * nearZ * farZ * fn;
+}
 
+/*!
+ * @brief set up infinite perspective projection matrix
+ *        with a left-hand coordinate system and a
+ *        clip-space of [-1, 1].
+ *
+ * @param[in]  fovy    field of view angle
+ * @param[in]  aspect  aspect ratio ( width / height )
+ * @param[in]  nearZ   near clipping plane
+ * @param[out] dest    result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_infinite_lh_no(float fovy,
+                               float aspect,
+                               float nearZ,
+                               mat4  dest) {
+  float f;
+
+  glm_mat4_zero(dest);
+
+  f  = 1.0f / tanf(fovy * 0.5f);
+
+  dest[0][0] = f / aspect;
+  dest[1][1] = f;
+  dest[2][2] = 1.0f;
+  dest[2][3] = 1.0f;
+  dest[3][2] =-2.0f * nearZ;
 }
 
 /*!
@@ -133,6 +166,20 @@ glm_perspective_default_lh_no(float aspect, mat4 dest) {
   glm_perspective_lh_no(GLM_PI_4f, aspect, 0.01f, 100.0f, dest);
 }
 
+/*!
+ * @brief set up infinite perspective projection matrix with default near
+ *        and angle values with a left-hand coordinate system and a
+ *        clip-space of [-1, 1].
+ *
+ * @param[in]  aspect aspect ratio ( width / height )
+ * @param[out] dest   result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_default_infinite_lh_no(float aspect, mat4 dest) {
+  glm_perspective_infinite_lh_no(GLM_PI_4f, aspect, 0.01f, dest);
+}
+
 /*!
  * @brief resize perspective matrix by aspect ratio ( width / height )
  *        this makes very easy to resize proj matrix when window /viewport

include/cglm/clipspace/persp_lh_zo.h

@@ -16,7 +16,12 @@
                                           float nearZ,
                                           float farZ,
                                           mat4  dest)
+   CGLM_INLINE void glm_perspective_infinite_lh_zo(float fovy,
+                                                   float aspect,
+                                                   float nearZ,
+                                                   mat4  dest)
    CGLM_INLINE void glm_perspective_default_lh_zo(float aspect, mat4 dest)
+   CGLM_INLINE void glm_perspective_default_infinite_lh_zo(float aspect, mat4 dest)
    CGLM_INLINE void glm_perspective_resize_lh_zo(float aspect, mat4 proj)
    CGLM_INLINE void glm_persp_move_far_lh_zo(mat4 proj,
                                              float deltaFar)
@@ -116,6 +121,35 @@ glm_perspective_lh_zo(float fovy,
   dest[3][2] = nearZ * farZ * fn;
 }
 
+/*!
+* @brief set up infinite perspective projection matrix
+ *        with a left-hand coordinate system and a
+ *        clip-space of [0, 1].
+ *
+ * @param[in]  fovy    field of view angle
+ * @param[in]  aspect  aspect ratio ( width / height )
+ * @param[in]  nearZ   near clipping plane
+ * @param[out] dest    result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_infinite_lh_zo(float fovy,
+                               float aspect,
+                               float nearZ,
+                               mat4  dest) {
+  float f;
+
+  glm_mat4_zero(dest);
+
+  f  = 1.0f / tanf(fovy * 0.5f);
+
+  dest[0][0] = f / aspect;
+  dest[1][1] = f;
+  dest[2][2] = 1.0f;
+  dest[2][3] = 1.0f;
+  dest[3][2] =-nearZ;
+}
+
 /*!
  * @brief extend perspective projection matrix's far distance with a
  *        left-hand coordinate system and a clip-space with depth values
@@ -144,7 +178,7 @@ glm_persp_move_far_lh_zo(mat4 proj, float deltaFar) {
 
 /*!
  * @brief set up perspective projection matrix with default near/far
- *        and angle values with a left-hand coordinate system and a 
+ *        and angle values with a left-hand coordinate system and a
  *        clip-space of [0, 1].
  *
  * @param[in]  aspect aspect ratio ( width / height )
@@ -156,6 +190,20 @@ glm_perspective_default_lh_zo(float aspect, mat4 dest) {
   glm_perspective_lh_zo(GLM_PI_4f, aspect, 0.01f, 100.0f, dest);
 }
 
+/*!
+ * @brief set up infinite perspective projection matrix with default near
+ *        and angle values with a left-hand coordinate system and a
+ *        clip-space of [0, 1].
+ *
+ * @param[in]  aspect aspect ratio ( width / height )
+ * @param[out] dest   result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_default_infinite_lh_zo(float aspect, mat4 dest) {
+  glm_perspective_infinite_lh_zo(GLM_PI_4f, aspect, 0.01f, dest);
+}
+
 /*!
  * @brief resize perspective matrix by aspect ratio ( width / height )
  *        this makes very easy to resize proj matrix when window /viewport

include/cglm/clipspace/persp_rh_no.h

@@ -16,7 +16,12 @@
                                           float nearZ,
                                           float farZ,
                                           mat4  dest)
+   CGLM_INLINE void glm_perspective_infinite_rh_no(float fovy,
+                                                   float aspect,
+                                                   float nearZ,
+                                                   mat4  dest)
    CGLM_INLINE void glm_perspective_default_rh_no(float aspect, mat4 dest)
+   CGLM_INLINE void glm_perspective_default_infinite_rh_no(float aspect, mat4 dest)
    CGLM_INLINE void glm_perspective_resize_rh_no(float aspect, mat4 proj)
    CGLM_INLINE void glm_persp_move_far_rh_no(mat4 proj,
                                              float deltaFar)
@@ -116,7 +121,35 @@ glm_perspective_rh_no(float fovy,
   dest[2][2] = (nearZ + farZ) * fn;
   dest[2][3] =-1.0f;
   dest[3][2] = 2.0f * nearZ * farZ * fn;
+}
 
+/*!
+ * @brief set up infinite perspective projection matrix
+ *        with a right-hand coordinate system and a
+ *        clip-space of [-1, 1].
+ *
+ * @param[in]  fovy    field of view angle
+ * @param[in]  aspect  aspect ratio ( width / height )
+ * @param[in]  nearZ   near clipping plane
+ * @param[out] dest    result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_infinite_rh_no(float fovy,
+                               float aspect,
+                               float nearZ,
+                               mat4  dest) {
+  float f;
+
+  glm_mat4_zero(dest);
+
+  f  = 1.0f / tanf(fovy * 0.5f);
+
+  dest[0][0] = f / aspect;
+  dest[1][1] = f;
+  dest[2][2] =-1.0f;
+  dest[2][3] =-1.0f;
+  dest[3][2] =-2.0f * nearZ;
 }
 
 /*!
@@ -133,6 +166,20 @@ glm_perspective_default_rh_no(float aspect, mat4 dest) {
   glm_perspective_rh_no(GLM_PI_4f, aspect, 0.01f, 100.0f, dest);
 }
 
+/*!
+ * @brief set up infinite perspective projection matrix with default near
+ *        and angle values with a right-hand coordinate system and a
+ *        clip-space of [-1, 1].
+ *
+ * @param[in]  aspect aspect ratio ( width / height )
+ * @param[out] dest   result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_default_infinite_rh_no(float aspect, mat4 dest) {
+  glm_perspective_infinite_rh_no(GLM_PI_4f, aspect, 0.01f, dest);
+}
+
 /*!
  * @brief resize perspective matrix by aspect ratio ( width / height )
  *        this makes very easy to resize proj matrix when window /viewport

include/cglm/clipspace/persp_rh_zo.h

@@ -16,7 +16,12 @@
                                           float nearZ,
                                           float farZ,
                                           mat4  dest)
+   CGLM_INLINE void glm_perspective_infinite_rh_zo(float fovy,
+                                                   float aspect,
+                                                   float nearZ,
+                                                   mat4  dest)
    CGLM_INLINE void glm_perspective_default_rh_zo(float aspect, mat4 dest)
+   CGLM_INLINE void glm_perspective_default_infinite_rh_zo(float aspect, mat4 dest)
    CGLM_INLINE void glm_perspective_resize_rh_zo(float aspect, mat4 proj)
    CGLM_INLINE void glm_persp_move_far_rh_zo(mat4 proj,
                                              float deltaFar)
@@ -116,6 +121,35 @@ glm_perspective_rh_zo(float fovy,
   dest[3][2] = nearZ * farZ * fn;
 }
 
+/*!
+ * @brief set up infinite perspective projection matrix
+ *        with a right-hand coordinate system and a
+ *        clip-space of [0, 1].
+ *
+ * @param[in]  fovy    field of view angle
+ * @param[in]  aspect  aspect ratio ( width / height )
+ * @param[in]  nearZ   near clipping plane
+ * @param[out] dest    result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_infinite_rh_zo(float fovy,
+                               float aspect,
+                               float nearZ,
+                               mat4  dest) {
+  float f;
+
+  glm_mat4_zero(dest);
+
+  f  = 1.0f / tanf(fovy * 0.5f);
+
+  dest[0][0] = f / aspect;
+  dest[1][1] = f;
+  dest[2][2] =-1.0f;
+  dest[2][3] =-1.0f;
+  dest[3][2] =-nearZ;
+}
+
 /*!
  * @brief set up perspective projection matrix with default near/far
  *        and angle values with a right-hand coordinate system and a
@@ -130,6 +164,20 @@ glm_perspective_default_rh_zo(float aspect, mat4 dest) {
   glm_perspective_rh_zo(GLM_PI_4f, aspect, 0.01f, 100.0f, dest);
 }
 
+/*!
+ * @brief set up infinite perspective projection matrix with default near
+ *        and angle values with a right-hand coordinate system and a
+ *        clip-space of [0, 1].
+ *
+ * @param[in]  aspect aspect ratio ( width / height )
+ * @param[out] dest   result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_default_infinite_rh_zo(float aspect, mat4 dest) {
+  glm_perspective_infinite_rh_zo(GLM_PI_4f, aspect, 0.01f, dest);
+}
+
 /*!
  * @brief resize perspective matrix by aspect ratio ( width / height )
  *        this makes very easy to resize proj matrix when window /viewport

src/cam.c

@@ -62,6 +62,12 @@ glmc_perspective(float fovy, float aspect, float nearZ, float farZ, mat4 dest) {
   glm_perspective(fovy, aspect, nearZ, farZ, dest);
 }
 
+CGLM_EXPORT
+void
+glmc_perspective_infinite(float fovy, float aspect, float nearZ, mat4 dest) {
+  glm_perspective_infinite(fovy, aspect, nearZ, dest);
+}
+
 CGLM_EXPORT
 void
 glmc_persp_move_far(mat4 proj, float deltaFar) {
@@ -74,6 +80,12 @@ glmc_perspective_default(float aspect, mat4 dest) {
   glm_perspective_default(aspect, dest);
 }
 
+CGLM_EXPORT
+void
+glmc_perspective_default_infinite(float aspect, mat4 dest) {
+  glm_perspective_default_infinite(aspect, dest);
+}
+
 CGLM_EXPORT
 void
 glmc_perspective_resize(float aspect, mat4 proj) {