change signature of refraction to let caller know if refraction occur…

…s or not

docs/source/vec2.rst

@@ -406,15 +406,19 @@ Functions documentation
       | *[in]*  **N**     *❗️ normalized ❗️* normal vector
       | *[out]* **dest**  destination: reflection result
 
-.. c:function:: void glm_vec2_refract(vec2 I, vec2 N, float eta, vec2 dest)
+.. c:function:: bool glm_vec2_refract(vec2 I, vec2 N, float eta, vec2 dest)
 
-    Refraction vector using entering ray, surface normal and refraction index
-
-    If the angle between the entering ray I and the surface normal N is too 
-    great for a given refraction index, the return value is zero
+    Computes refraction vector for an incident vector and a surface normal.
+   
+    Calculates the refraction vector based on Snell's law. If total internal reflection
+    occurs (angle too great given eta), dest is set to zero and returns false.
+    Otherwise, computes refraction vector, stores it in dest, and returns true.
 
     Parameters:
       | *[in]*  **I**     *❗️ normalized ❗️* incident vector
       | *[in]*  **N**     *❗️ normalized ❗️* normal vector
-      | *[in]*  **eta**   ratio of indices of refraction ( η )
-      | *[out]* **dest**  destination: refraction result
+      | *[in]*  **eta**   ratio of indices of refraction (incident/transmitted)
+      | *[out]* **dest**  refraction vector if refraction occurs; zero vector otherwise
+
+    Returns:
+      returns true if refraction occurs; false if total internal reflection occurs.

docs/source/vec3.rst

@@ -535,15 +535,20 @@ Functions documentation
       | *[in]*  **N**     *❗️ normalized ❗️* normal vector
       | *[out]* **dest**  destination: reflection result
 
-.. c:function:: void glm_vec3_refract(vec3 I, vec3 N, float eta, vec3 dest)
+.. c:function:: bool glm_vec3_refract(vec3 I, vec3 N, float eta, vec3 dest)
 
-    Refraction vector using entering ray, surface normal and refraction index
-
-    If the angle between the entering ray I and the surface normal N is too 
-    great for a given refraction index, the return value is zero
+    
+    Computes refraction vector for an incident vector and a surface normal.
+   
+    Calculates the refraction vector based on Snell's law. If total internal reflection
+    occurs (angle too great given eta), dest is set to zero and returns false.
+    Otherwise, computes refraction vector, stores it in dest, and returns true.
 
     Parameters:
       | *[in]*  **I**     *❗️ normalized ❗️* incident vector
       | *[in]*  **N**     *❗️ normalized ❗️* normal vector
-      | *[in]*  **eta**   ratio of indices of refraction ( η )
-      | *[out]* **dest**  destination: refraction result
+      | *[in]*  **eta**   ratio of indices of refraction (incident/transmitted)
+      | *[out]* **dest**  refraction vector if refraction occurs; zero vector otherwise
+
+    Returns:
+      returns true if refraction occurs; false if total internal reflection occurs.

docs/source/vec4.rst

@@ -427,7 +427,7 @@ Functions documentation
       | *[in]*  **src**  pointer to an array of floats
       | *[out]* **dest** destination vector
 
-.. c:function:: void glm_vec4_reflect(vec4 I, vec4 N, vec4 dest) 
+.. c:function:: bool glm_vec4_reflect(vec4 I, vec4 N, vec4 dest) 
 
     Reflection vector using an incident ray and a surface normal
 
@@ -436,19 +436,23 @@ Functions documentation
       | *[in]*  **N**     *❗️ normalized ❗️* normal vector
       | *[out]* **dest**  destination: reflection result
 
-.. c:function:: void glm_vec4_refract(vec4 I, vec4 N, float eta, vec4 dest)
+.. c:function:: bool glm_vec4_refract(vec4 I, vec4 N, float eta, vec4 dest)
 
-    Refraction vector using entering ray, surface normal and refraction index
-
-    If the angle between the entering ray I and the surface normal N is too 
-    great for a given refraction index, the return value is zero
-
-    this implementation does not explicitly preserve the 'w' component of the
+    computes refraction vector for an incident vector and a surface normal.
+   
+    Calculates the refraction vector based on Snell's law. If total internal reflection
+    occurs (angle too great given eta), dest is set to zero and returns false.
+    Otherwise, computes refraction vector, stores it in dest, and returns true.
+   
+    This implementation does not explicitly preserve the 'w' component of the
     incident vector 'I' in the output 'dest', users requiring the preservation of
     the 'w' component should manually adjust 'dest' after calling this function.
 
     Parameters:
       | *[in]*  **I**     *❗️ normalized ❗️* incident vector
       | *[in]*  **N**     *❗️ normalized ❗️* normal vector
-      | *[in]*  **eta**   ratio of indices of refraction ( η )
-      | *[out]* **dest**  destination: refraction result
+      | *[in]*  **eta**   ratio of indices of refraction (incident/transmitted)
+      | *[out]* **dest**  refraction vector if refraction occurs; zero vector otherwise
+
+    Returns:
+      returns true if refraction occurs; false if total internal reflection occurs.

include/cglm/call/vec2.h

@@ -202,7 +202,7 @@ void
 glmc_vec2_reflect(vec2 I, vec2 N, vec2 dest);
 
 CGLM_EXPORT
-void
+bool
 glmc_vec2_refract(vec2 I, vec2 N, float eta, vec2 dest);
 
 #ifdef __cplusplus

include/cglm/call/vec3.h

@@ -343,7 +343,7 @@ void
 glmc_vec3_reflect(vec3 I, vec3 N, vec3 dest);
 
 CGLM_EXPORT
-void
+bool
 glmc_vec3_refract(vec3 I, vec3 N, float eta, vec3 dest);
 
 #ifdef __cplusplus

include/cglm/call/vec4.h

@@ -316,7 +316,7 @@ void
 glmc_vec4_reflect(vec4 I, vec4 N, vec4 dest);
 
 CGLM_EXPORT
-void
+bool
 glmc_vec4_refract(vec4 I, vec4 N, float eta, vec4 dest);
 
 #ifdef __cplusplus

include/cglm/struct/vec2.h

@@ -55,7 +55,7 @@
    CGLM_INLINE vec2s glms_vec2_lerp(vec2s from, vec2s to, float t)
    CGLM_INLINE vec2s glms_vec2_make(float * restrict src)
    CGLM_INLINE vec2s glms_vec2_reflect(vec2s I, vec2s N)
-   CGLM_INLINE vec2s glms_vec2_refract(vec2s I, vec2s N, float eta)
+   CGLM_INLINE bool  glms_vec2_refract(vec2s I, vec2s N, float eta, vec2s *dest)
  */
 
 #ifndef cglms_vec2s_h
@@ -709,22 +709,23 @@ glms_vec2_(reflect)(vec2s I, vec2s N) {
 }
 
 /*!
- * @brief refraction vector using entering ray, surface normal and refraction index
+ * @brief computes refraction vector for an incident vector and a surface normal.
  *
- * if the angle between the entering ray I and the surface normal N is too great
- * for a given refraction index, the return value is zero
+ * calculates the refraction vector based on Snell's law. If total internal reflection
+ * occurs (angle too great given eta), dest is set to zero and returns false.
+ * Otherwise, computes refraction vector, stores it in dest, and returns true.
  *
  * @param[in]  I    normalized incident vector
  * @param[in]  N    normalized normal vector
- * @param[in]  eta  ratio of indices of refraction
- * @param[out] dest refraction result
+ * @param[in]  eta  ratio of indices of refraction (incident/transmitted)
+ * @param[out] dest refraction vector if refraction occurs; zero vector otherwise
+ *
+ * @returns true if refraction occurs; false if total internal reflection occurs.
  */
 CGLM_INLINE
-vec2s
-glms_vec2_(refract)(vec2s I, vec2s N, float eta) {
-  vec2s dest;
-  glm_vec2_refract(I.raw, N.raw, eta, dest.raw);
-  return dest;
+bool
+glms_vec2_(refract)(vec2s I, vec2s N, float eta, vec2s * __restrict dest) {
+  return glm_vec2_refract(I.raw, N.raw, eta, dest->raw);
 }
 
 #endif /* cglms_vec2s_h */

include/cglm/struct/vec3.h

@@ -78,7 +78,7 @@
    CGLM_INLINE vec3s glms_vec3_make(float * restrict src);
    CGLM_INLINE vec3s glms_vec3_faceforward(vec3s N, vec3s I, vec3s Nref);
    CGLM_INLINE vec3s glms_vec3_reflect(vec3s I, vec3s N);
-   CGLM_INLINE vec3s glms_vec3_refract(vec3s I, vec3s N, float eta);
+   CGLM_INLINE bool  glms_vec3_refract(vec3s I, vec3s N, float eta, vec3s *dest)
 
  Convenient:
    CGLM_INLINE vec3s glms_cross(vec3s a, vec3s b);
@@ -1120,22 +1120,23 @@ glms_vec3_(reflect)(vec3s I, vec3s N) {
 }
 
 /*!
- * @brief refraction vector using entering ray, surface normal and refraction index
+ * @brief computes refraction vector for an incident vector and a surface normal.
  *
- * if the angle between the entering ray I and the surface normal N is too great
- * for a given refraction index, the return value is zero
+ * calculates the refraction vector based on Snell's law. If total internal reflection
+ * occurs (angle too great given eta), dest is set to zero and returns false.
+ * Otherwise, computes refraction vector, stores it in dest, and returns true.
  *
  * @param[in]  I    normalized incident vector
  * @param[in]  N    normalized normal vector
- * @param[in]  eta  ratio of indices of refraction
- * @returns refraction result
+ * @param[in]  eta  ratio of indices of refraction (incident/transmitted)
+ * @param[out] dest refraction vector if refraction occurs; zero vector otherwise
+ *
+ * @returns true if refraction occurs; false if total internal reflection occurs.
  */
 CGLM_INLINE
-vec3s
-glms_vec3_(refract)(vec3s I, vec3s N, float eta) {
-  vec3s dest;
-  glm_vec3_refract(I.raw, N.raw, eta, dest.raw);
-  return dest;
+bool
+glms_vec3_(refract)(vec3s I, vec3s N, float eta, vec3s * __restrict dest) {
+  return glm_vec3_refract(I.raw, N.raw, eta, dest->raw);
 }
 
 #endif /* cglms_vec3s_h */

include/cglm/struct/vec4.h

@@ -68,7 +68,7 @@
    CGLM_INLINE vec4s glms_vec4_swizzle(vec4s v, int mask);
    CGLM_INLINE vec4s glms_vec4_make(float * restrict src);
    CGLM_INLINE vec4s glms_vec4_reflect(vec4s I, vec4s N);
-   CGLM_INLINE vec4s glms_vec4_refract(vec4s I, vec4s N, float eta);
+   CGLM_INLINE bool  glms_vec4_refract(vec4s I, vec4s N, float eta, vec4s *dest)
  */
 
 #ifndef cglms_vec4s_h
@@ -945,26 +945,27 @@ glms_vec4_(reflect)(vec4s I, vec4s N) {
 }
 
 /*!
- * @brief refraction vector using entering ray, surface normal and refraction index
+ * @brief computes refraction vector for an incident vector and a surface normal.
  *
- * if the angle between the entering ray I and the surface normal N is too great
- * for a given refraction index, the return value is zero
+ * calculates the refraction vector based on Snell's law. If total internal reflection
+ * occurs (angle too great given eta), dest is set to zero and returns false.
+ * Otherwise, computes refraction vector, stores it in dest, and returns true.
  *
  * this implementation does not explicitly preserve the 'w' component of the
  * incident vector 'I' in the output 'dest', users requiring the preservation of
  * the 'w' component should manually adjust 'dest' after calling this function.
  *
  * @param[in]  I    normalized incident vector
  * @param[in]  N    normalized normal vector
- * @param[in]  eta  ratio of indices of refraction
- * @returns refraction result
+ * @param[in]  eta  ratio of indices of refraction (incident/transmitted)
+ * @param[out] dest refraction vector if refraction occurs; zero vector otherwise
+ *
+ * @returns true if refraction occurs; false if total internal reflection occurs.
  */
 CGLM_INLINE
-vec4s
-glms_vec4_(refract)(vec4s I, vec4s N, float eta) {
-  vec4s dest;
-  glm_vec4_refract(I.raw, N.raw, eta, dest.raw);
-  return dest;
+bool
+glms_vec4_(refract)(vec4s I, vec4s N, float eta, vec4s * __restrict dest) {
+  return glm_vec4_refract(I.raw, N.raw, eta, dest->raw);
 }
 
 #endif /* cglms_vec4s_h */

include/cglm/vec2.h

@@ -729,18 +729,21 @@ glm_vec2_reflect(vec2 I, vec2 N, vec2 dest) {
 }
 
 /*!
- * @brief refraction vector using entering ray, surface normal and refraction index
+ * @brief computes refraction vector for an incident vector and a surface normal.
  *
- * if the angle between the entering ray I and the surface normal N is too great
- * for a given refraction index, the return value is zero
+ * calculates the refraction vector based on Snell's law. If total internal reflection
+ * occurs (angle too great given eta), dest is set to zero and returns false.
+ * Otherwise, computes refraction vector, stores it in dest, and returns true.
  *
  * @param[in]  I    normalized incident vector
  * @param[in]  N    normalized normal vector
- * @param[in]  eta  ratio of indices of refraction
- * @param[out] dest refraction result
+ * @param[in]  eta  ratio of indices of refraction (incident/transmitted)
+ * @param[out] dest refraction vector if refraction occurs; zero vector otherwise
+ *
+ * @returns true if refraction occurs; false if total internal reflection occurs.
  */
 CGLM_INLINE
-void 
+bool
 glm_vec2_refract(vec2 I, vec2 N, float eta, vec2 dest) {
   float ndi, eni, k;
 
@@ -750,11 +753,12 @@ glm_vec2_refract(vec2 I, vec2 N, float eta, vec2 dest) {
 
   if (k < 0.0f) {
     glm_vec2_zero(dest);
-    return;
+    return false;
   }
 
   glm_vec2_scale(I, eta, dest);
   glm_vec2_mulsubs(N, eni + sqrtf(k), dest);
+  return true;
 }
 
 #endif /* cglm_vec2_h */

include/cglm/vec3.h

@@ -1243,18 +1243,21 @@ glm_vec3_reflect(vec3 I, vec3 N, vec3 dest) {
 }
 
 /*!
- * @brief refraction vector using entering ray, surface normal and refraction index
+ * @brief computes refraction vector for an incident vector and a surface normal.
  *
- * if the angle between the entering ray I and the surface normal N is too great
- * for a given refraction index, the return value is zero
+ * calculates the refraction vector based on Snell's law. If total internal reflection
+ * occurs (angle too great given eta), dest is set to zero and returns false.
+ * Otherwise, computes refraction vector, stores it in dest, and returns true.
  *
  * @param[in]  I    normalized incident vector
  * @param[in]  N    normalized normal vector
- * @param[in]  eta  ratio of indices of refraction
- * @param[out] dest refraction result
+ * @param[in]  eta  ratio of indices of refraction (incident/transmitted)
+ * @param[out] dest refraction vector if refraction occurs; zero vector otherwise
+ *
+ * @returns true if refraction occurs; false if total internal reflection occurs.
  */
 CGLM_INLINE
-void
+bool
 glm_vec3_refract(vec3 I, vec3 N, float eta, vec3 dest) {
   float ndi, eni, k;
 
@@ -1264,11 +1267,12 @@ glm_vec3_refract(vec3 I, vec3 N, float eta, vec3 dest) {
 
   if (k < 0.0f) {
     glm_vec3_zero(dest);
-    return;
+    return false;
   }
 
   glm_vec3_scale(I, eta, dest);
   glm_vec3_mulsubs(N, eni + sqrtf(k), dest);
+  return true;
 }
 
 #endif /* cglm_vec3_h */

include/cglm/vec4.h

@@ -1326,22 +1326,25 @@ glm_vec4_reflect(vec4 I, vec4 N, vec4 dest) {
 }
 
 /*!
- * @brief refraction vector using entering ray, surface normal and refraction index
+ * @brief computes refraction vector for an incident vector and a surface normal.
  *
- * if the angle between the entering ray I and the surface normal N is too great
- * for a given refraction index, the return value is zero
+ * calculates the refraction vector based on Snell's law. If total internal reflection
+ * occurs (angle too great given eta), dest is set to zero and returns false.
+ * Otherwise, computes refraction vector, stores it in dest, and returns true.
  *
  * this implementation does not explicitly preserve the 'w' component of the
  * incident vector 'I' in the output 'dest', users requiring the preservation of
  * the 'w' component should manually adjust 'dest' after calling this function.
  *
  * @param[in]  I    normalized incident vector
  * @param[in]  N    normalized normal vector
- * @param[in]  eta  ratio of indices of refraction
- * @param[out] dest refraction result
+ * @param[in]  eta  ratio of indices of refraction (incident/transmitted)
+ * @param[out] dest refraction vector if refraction occurs; zero vector otherwise
+ *
+ * @returns true if refraction occurs; false if total internal reflection occurs.
  */
 CGLM_INLINE
-void 
+bool
 glm_vec4_refract(vec4 I, vec4 N, float eta, vec4 dest) {
   float ndi, eni, k;
 
@@ -1351,11 +1354,12 @@ glm_vec4_refract(vec4 I, vec4 N, float eta, vec4 dest) {
 
   if (k < 0.0f) {
     glm_vec4_zero(dest);
-    return;
+    return false;
   }
 
   glm_vec4_scale(I, eta, dest);
   glm_vec4_mulsubs(N, eni + sqrtf(k), dest);
+  return true;
 }
 
 #endif /* cglm_vec4_h */

src/vec2.c

@@ -310,7 +310,7 @@ glmc_vec2_reflect(vec2 I, vec2 N, vec2 dest) {
 }
 
 CGLM_EXPORT
-void
+bool
 glmc_vec2_refract(vec2 I, vec2 N, float eta, vec2 dest) {
-  glm_vec2_refract(I, N, eta, dest);
+  return glm_vec2_refract(I, N, eta, dest);
 }