glm_utils.hpp

#ifndef GLM_UTILS_HPP
#define GLM_UTILS_HPP

#define GLM_ENABLE_EXPERIMENTAL
#include <glm/glm.hpp>
#include <string>

#include "sbpt_generated_includes.hpp"

namespace glm_utils {

enum class Component { x, y, z };

/// @brief Identity matrix (4x4) constant.
extern glm::mat4 identity_matrix;

/// @brief Zero matrix (4x4) constant.
extern glm::mat4 zero_matrix;

/// @brief Zero vector in R³ (3D space).
extern glm::vec3 zero_R3;

/// @brief Unit vector with all components equal to 1 in R³.
extern glm::vec3 one_R3;
extern glm::vec3 minus_one_R3;

/// @brief Zero vector in R² (2D space).
extern glm::vec2 zero_R2;

/// @brief Unit vector with all components equal to 1 in R².
extern glm::vec2 one_R2;
extern glm::vec2 minus_one_R2;

/// @brief Unit vector along the X-axis (1, 0, 0).
extern glm::vec3 x;
extern glm::vec2 x_R2;

/// @brief Unit vector along the Y-axis (0, 1, 0).
extern glm::vec3 y;
extern glm::vec2 y_R2;

/// @brief Unit vector along the Z-axis (0, 0, 1).
extern glm::vec3 z;

template <typename T1, typename T2> glm::vec2 tuple_to_vec2(const std::tuple<T1, T2> &t) {
    return glm::vec2{static_cast<float>(std::get<0>(t)), static_cast<float>(std::get<1>(t))};
}

template <typename T1, typename T2, typename T3> glm::vec3 tuple_to_vec3(const std::tuple<T1, T2, T3> &t) {
    return glm::vec3{static_cast<float>(std::get<0>(t)), static_cast<float>(std::get<1>(t)),
                     static_cast<float>(std::get<2>(t))};
}

template <typename T1, typename T2, typename T3, typename T4>
glm::vec4 tuple_to_vec4(const std::tuple<T1, T2, T3, T4> &t) {
    return glm::vec4{static_cast<float>(std::get<0>(t)), static_cast<float>(std::get<1>(t)),
                     static_cast<float>(std::get<2>(t)), static_cast<float>(std::get<3>(t))};
}

/**
 * @brief Lifts a 2D vector into 3D by inserting a new component at a specified position.
 *
 * This function takes a 2D vector `v` and a float `value`, and returns a 3D vector
 * where `value` is inserted at the position specified by `pos`. The remaining
 * components of the original vector are shifted accordingly.
 *
 * @param v The original 2D vector to lift.
 * @param value The value to insert into the new 3D vector.
 * @param pos The position at which to insert `value`. Should be one of the
 *        `LiftPosition3` enum values: `X`, `Y`, or `Z`.
 * @return A 3D vector with `value` inserted at the specified position.
 *
 * @note This function does not modify the original vector.
 * @see LiftPosition3
 */
glm::vec3 lift(const glm::vec2 &v, float value, Component component);

/**
 * @brief Projects a 3D vector into 2D by removing a specified component.
 *
 * This function takes a 3D vector `v` and returns a 2D vector where the component
 * specified by `component` is removed. The remaining components are shifted to fill
 * the gap.
 *
 * @param v The original 3D vector to project.
 * @param component The component to remove from the 3D vector. Should be one of the
 *        `Component` enum values: `X`, `Y`, or `Z`.
 * @return A 2D vector with the specified component removed.
 *
 * @note This function does not modify the original vector.
 * @see Component
 */
glm::vec2 drop(const glm::vec3 &v, Component component);

/**
 * @brief Returns a copy of a 3D vector with the specified component set to a new value.
 *
 * This function does not modify the original vector. The component to change is
 * specified using the `Component` enum.
 *
 * @param v The original 3D vector.
 * @param component The component to set (Component::x, Component::y, or Component::z).
 * @param value The new value to assign to the specified component.
 * @return A copy of the vector with the specified component modified.
 */
glm::vec3 set_component(const glm::vec3 &v, Component component, float value);

/**
 * Computes the distance between two vectors along a single component.
 *
 * This function measures how far `b` is from `a` along the specified
 * `component` (x, y, or z). The distance is **signed**, meaning it will
 * be positive if `b` is in the positive direction of the component from `a`,
 * negative if it is in the opposite direction, and zero if the two positions
 * coincide along that component.
 *
 * @param a The first vector.
 * @param b The second vector.
 * @param component The component (x, y, or z) along which to measure the distance.
 * @return The signed distance along the specified component.
 */
float signed_component_distance(const glm::vec3 &a, const glm::vec3 &b, const Component &component);
float signed_component_distance(const glm::vec2 &a, const glm::vec2 &b, const Component &component);

// @see component_distance, but unsigned
float component_distance(const glm::vec3 &a, const glm::vec3 &b, const Component &component);
float component_distance(const glm::vec2 &a, const glm::vec2 &b, const Component &component);

/**
 * @brief Computes the normalized cross product of two 3D vectors.
 *
 * @param a First vector.
 * @param b Second vector.
 * @return glm::vec3 Normalized vector perpendicular to both `a` and `b`.
 *
 * @note this is useful when you are only using the cross product to get a vector which is perpendicular to two others
 * and you dont' want it's length to be different (which is what occurs with the cross product)
 */
inline glm::vec3 normalized_cross(const glm::vec3 &a, const glm::vec3 &b) { return glm::normalize(glm::cross(a, b)); }

/**
 * @brief Parses a string into a 3D vector (vec3).
 *
 * The input string should be in a format like "x,y,z".
 *
 * @param s Input string representing a 3D vector.
 * @return glm::vec3 Parsed vector.
 */
glm::vec3 parse_vec3(const std::string &s);

/**
 * @brief Parses a string into a 2D vector (vec2).
 *
 * The input string should be in a format like "x,y".
 *
 * @param s Input string representing a 2D vector.
 * @return glm::vec2 Parsed vector.
 */
glm::vec2 parse_vec2(const std::string &s);

/**
 * @brief Computes the midpoint between two 3D points.
 *
 * @param a First point.
 * @param b Second point.
 * @return glm::vec3 Midpoint between a and b.
 */
glm::vec3 get_midpoint(const glm::vec3 &a, const glm::vec3 &b);

/**
 * @brief Linearly interpolates between two 3D vectors.
 *
 * @param a Start vector.
 * @param b End vector.
 * @param t Interpolation factor in [0, 1].
 * @return glm::vec3 Interpolated vector.
 */
glm::vec3 linearly_interpolate(const glm::vec3 &a, const glm::vec3 &b, float t);

/**
 * @brief Rotates a 3D vector to align with a forward direction.
 *
 * @param forward The target forward direction.
 * @param to_be_rotated The vector to rotate.
 * @return glm::vec3 Rotated vector aligned with forward.
 */
glm::vec3 rotate_vector_to_align_with_forward(const glm::vec3 &forward, const glm::vec3 &to_be_rotated);

/**
 * @brief Rotates a 2D vector to align with a forward direction.
 *
 * @param forward The target forward direction in 2D.
 * @param to_be_rotated The 2D vector to rotate.
 * @return glm::vec2 Rotated vector aligned with forward.
 */
glm::vec2 rotate_vector_to_align_with_forward(const glm::vec2 &forward, const glm::vec2 &to_be_rotated);

} // namespace glm_utils

#endif // GLM_UTILS_HPP