From da5755807866cbcadc47ab62850e06882f586cc7 Mon Sep 17 00:00:00 2001 From: Recep Aslantas Date: Fri, 22 Mar 2024 22:30:22 +0300 Subject: [PATCH] docs for new ray functions --- docs/source/ray.rst | 36 ++++++++++++++++++++++++++++++++++++ docs/source/vec2.rst | 24 ++++++++++++++++++++++++ docs/source/vec3.rst | 35 +++++++++++++++++++++++++++++++++++ docs/source/vec4.rst | 28 ++++++++++++++++++++++++++++ include/cglm/ray.h | 7 +++++++ include/cglm/vec3.h | 4 ++-- 6 files changed, 132 insertions(+), 2 deletions(-) diff --git a/docs/source/ray.rst b/docs/source/ray.rst index c5faf33..ab89b7a 100644 --- a/docs/source/ray.rst +++ b/docs/source/ray.rst @@ -13,6 +13,8 @@ Table of contents (click to go): Functions: 1. :c:func:`glm_ray_triangle` +#. :c:func:`glm_ray_sphere` +#. :c:func:`glm_ray_at` Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ @@ -29,3 +31,37 @@ Functions documentation | *[in]* **v2** third vertex of triangle | *[in, out]* **d** float pointer to save distance to intersection | *[out]* **intersection** whether there is intersection + +.. c:function:: bool glm_ray_sphere(vec3 origin, vec3 dir, vec4 s, float * __restrict t1, float * __restrict t2) + + ray sphere intersection + + - t1 > 0, t2 > 0: ray intersects the sphere at t1 and t2 both ahead of the origin + - t1 < 0, t2 > 0: ray starts inside the sphere, exits at t2 + - t1 < 0, t2 < 0: no intersection ahead of the ray + - the caller can check if the intersection points (t1 and t2) fall within a + specific range (for example, tmin < t1, t2 < tmax) to determine if the + intersections are within a desired segment of the ray + + Parameters: + | *[in]* **origin** ray origin + | *[in]* **dir** normalized ray direction + | *[in]* **s** sphere [center.x, center.y, center.z, radii] + | *[out]* **t1** near point1 (closer to origin) + | *[out]* **t2** far point2 (farther from origin) + + Return: + | whether there is intersection + +.. c:function:: bool glm_ray_at(vec3 orig, vec3 dir, float t, vec3 point) + + point using t by 𝐏(𝑡)=𝐀+𝑡𝐛 + + Parameters: + | *[in]* **origin** ray origin + | *[in]* **dir** ray direction + | *[out]* **t** parameter + | *[out]* **point** point at t + + Return: + | point at t diff --git a/docs/source/vec2.rst b/docs/source/vec2.rst index 102f4fa..8b1bdf0 100644 --- a/docs/source/vec2.rst +++ b/docs/source/vec2.rst @@ -53,6 +53,8 @@ Functions: #. :c:func:`glm_vec2_clamp` #. :c:func:`glm_vec2_lerp` #. :c:func:`glm_vec2_make` +#. :c:func:`glm_vec2_reflect` +#. :c:func:`glm_vec2_refract` Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ @@ -394,3 +396,25 @@ Functions documentation Parameters: | *[in]* **src** pointer to an array of floats | *[out]* **dest** destination vector + +.. c:function:: void glm_vec2_reflect(vec2 I, vec2 N, vec2 dest) + + Reflection vector using an incident ray and a surface normal + + Parameters: + | *[in]* **I** incident vector + | *[in]* **N** *❗️ normalized ❗️* normal vector + | *[out]* **dest** destination: reflection result + +.. c:function:: void 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 + + Parameters: + | *[in]* **I** *❗️ normalized ❗️* incident vector + | *[in]* **N** *❗️ normalized ❗️* normal vector + | *[in]* **eta** ratio of indices of refraction ( η ) + | *[out]* **dest** destination: refraction result diff --git a/docs/source/vec3.rst b/docs/source/vec3.rst index c7d92c8..07412c6 100644 --- a/docs/source/vec3.rst +++ b/docs/source/vec3.rst @@ -80,6 +80,9 @@ Functions: #. :c:func:`glm_vec3_clamp` #. :c:func:`glm_vec3_lerp` #. :c:func:`glm_vec3_make` +#. :c:func:`glm_vec3_faceforward` +#. :c:func:`glm_vec3_reflect` +#. :c:func:`glm_vec3_refract` Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ @@ -512,3 +515,35 @@ Functions documentation Parameters: | *[in]* **src** pointer to an array of floats | *[out]* **dest** destination vector + +.. c:function:: void glm_vec3_faceforward(vec3 N, vec3 I, vec3 Nref, vec3 dest) + + A vector pointing in the same direction as another + + Parameters: + | *[in]* **N** vector to orient + | *[in]* **I** incident vector + | *[in]* **Nref** reference vector + | *[out]* **dest** destination: oriented vector, pointing away from the surface. + +.. c:function:: void glm_vec3_reflect(vec3 I, vec3 N, vec3 dest) + + Reflection vector using an incident ray and a surface normal + + Parameters: + | *[in]* **I** incident vector + | *[in]* **N** *❗️ normalized ❗️* normal vector + | *[out]* **dest** destination: reflection result + +.. c:function:: void 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 + + Parameters: + | *[in]* **I** *❗️ normalized ❗️* incident vector + | *[in]* **N** *❗️ normalized ❗️* normal vector + | *[in]* **eta** ratio of indices of refraction ( η ) + | *[out]* **dest** destination: refraction result diff --git a/docs/source/vec4.rst b/docs/source/vec4.rst index 4281816..df270e7 100644 --- a/docs/source/vec4.rst +++ b/docs/source/vec4.rst @@ -60,6 +60,8 @@ Functions: #. :c:func:`glm_vec4_lerp` #. :c:func:`glm_vec4_cubic` #. :c:func:`glm_vec4_make` +#. :c:func:`glm_vec4_reflect` +#. :c:func:`glm_vec4_refract` Functions documentation ~~~~~~~~~~~~~~~~~~~~~~~ @@ -424,3 +426,29 @@ Functions documentation Parameters: | *[in]* **src** pointer to an array of floats | *[out]* **dest** destination vector + +.. c:function:: void glm_vec4_reflect(vec4 I, vec4 N, vec4 dest) + + Reflection vector using an incident ray and a surface normal + + Parameters: + | *[in]* **I** incident vector + | *[in]* **N** *❗️ normalized ❗️* normal vector + | *[out]* **dest** destination: reflection result + +.. c:function:: void 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 + 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 diff --git a/include/cglm/ray.h b/include/cglm/ray.h index d815166..38e171a 100644 --- a/include/cglm/ray.h +++ b/include/cglm/ray.h @@ -82,6 +82,13 @@ glm_ray_triangle(vec3 origin, /*! * @brief ray sphere intersection * + * - t1 > 0, t2 > 0: ray intersects the sphere at t1 and t2 both ahead of the origin + * - t1 < 0, t2 > 0: ray starts inside the sphere, exits at t2 + * - t1 < 0, t2 < 0: no intersection ahead of the ray + * - the caller can check if the intersection points (t1 and t2) fall within a + * specific range (for example, tmin < t1, t2 < tmax) to determine if the + * intersections are within a desired segment of the ray + * * @param[in] origin ray origin * @param[out] dir normalized ray direction * @param[in] s sphere [center.x, center.y, center.z, radii] diff --git a/include/cglm/vec3.h b/include/cglm/vec3.h index 1fdd483..b3dcfea 100644 --- a/include/cglm/vec3.h +++ b/include/cglm/vec3.h @@ -1210,10 +1210,10 @@ glm_vec3_make(const float * __restrict src, vec3 dest) { * * orients a vector to point away from a surface as defined by its normal * - * @param[in] N vector to orient. + * @param[in] N vector to orient * @param[in] I incident vector * @param[in] Nref reference vector - * @param[out] dest oriented vector, pointing away from the surface. + * @param[out] dest oriented vector, pointing away from the surface */ CGLM_INLINE void