Merge pull request #685 from themuffinator/codex/add-runtime-validation-for-division-operators

Guard Vector3 division against zero divisors

Author: themuffinator

src/shared/q_vec3.hpp

@@ -18,6 +18,7 @@
 
 #pragma once
 #include <array>
+#include <cassert>
 #include <cmath>
 #include <stdexcept>
 #include <type_traits>
@@ -26,11 +27,33 @@
 using nullptr_t = std::nullptr_t;
 
 struct Vector3 {
+	static constexpr float kDivisionEpsilon = 1.0e-6f;
+
 	std::array<float, 3> components{ 0.0f, 0.0f, 0.0f };
 	float& x;
 	float& y;
 	float& z;
 
+	/*
+	=============
+	SafeDivisor
+
+	Clamps divisors away from zero while asserting in debug builds.
+	=============
+	*/
+	[[nodiscard]] static inline float SafeDivisor(const float divisor) {
+		const bool near_zero = divisor > -kDivisionEpsilon && divisor < kDivisionEpsilon;
+
+		#ifndef NDEBUG
+		assert(!near_zero && "Vector3 division by zero or near-zero divisor");
+		#endif
+
+		if (near_zero)
+			return divisor >= 0.0f ? kDivisionEpsilon : -kDivisionEpsilon;
+
+		return divisor;
+	}
+
 	/*
 	=============
 	Vector3
@@ -159,12 +182,27 @@ struct Vector3 {
 	[[nodiscard]] constexpr Vector3 operator+(const Vector3& v) const {
 		return { x + v.x, y + v.y, z + v.z };
 	}
-	[[nodiscard]] constexpr Vector3 operator/(const Vector3& v) const {
-		return { x / v.x, y / v.y, z / v.z };
+	/*
+	=============
+	operator/
+
+	Divides component-wise by another vector using guarded divisors.
+	=============
+	*/
+	[[nodiscard]] inline Vector3 operator/(const Vector3& v) const {
+	return { x / SafeDivisor(v.x), y / SafeDivisor(v.y), z / SafeDivisor(v.z) };
 	}
 	template<typename T, typename = std::enable_if_t<std::is_floating_point_v<T> || std::is_integral_v<T>>>
-	[[nodiscard]] constexpr Vector3 operator/(const T& v) const {
-		return { static_cast<float>(x / v), static_cast<float>(y / v), static_cast<float>(z / v) };
+	/*
+	=============
+	operator/
+
+	Divides each component by a scalar using a guarded divisor.
+	=============
+	*/
+	[[nodiscard]] inline Vector3 operator/(const T& v) const {
+	const float divisor = SafeDivisor(static_cast<float>(v));
+	return { static_cast<float>(x / divisor), static_cast<float>(y / divisor), static_cast<float>(z / divisor) };
 	}
 	template<typename T, typename = std::enable_if_t<std::is_floating_point_v<T> || std::is_integral_v<T>>>
 	[[nodiscard]] constexpr Vector3 operator*(const T& v) const {

tests/test_vector3_division.cpp

@@ -0,0 +1,49 @@
+/*Copyright (c) 2024 The DarkMatter Project
+Licensed under the GNU General Public License 2.0.
+
+test_vector3_division.cpp implementation.*/
+
+#include <cassert>
+#include <cmath>
+
+#include "shared/q_vec3.hpp"
+
+/*
+=============
+main
+
+Validates Vector3 division behavior when divisors are zero or near-zero.
+=============
+*/
+int main() {
+	Vector3 numerator{ 1.0f, -2.0f, 3.0f };
+	Vector3 nearZeroDivisor{ 0.0f, 1.0e-8f, 4.0f };
+
+	Vector3 vectorResult = numerator / nearZeroDivisor;
+	assert(std::isfinite(vectorResult.x));
+	assert(std::isfinite(vectorResult.y));
+	assert(vectorResult.z == 0.75f);
+	const float expectedVectorX = 1.0f / Vector3::kDivisionEpsilon;
+	const float expectedVectorY = -2.0f / Vector3::kDivisionEpsilon;
+	assert(std::fabs(vectorResult.x - expectedVectorX) < 1.0f);
+	assert(std::fabs(vectorResult.y - expectedVectorY) < 1.0f);
+
+	Vector3 scalarResult = numerator / 0.0f;
+	assert(std::isfinite(scalarResult.x));
+	assert(std::isfinite(scalarResult.y));
+	assert(scalarResult.z == 3.0f / Vector3::kDivisionEpsilon);
+	const float expectedScalarX = 1.0f / Vector3::kDivisionEpsilon;
+	const float expectedScalarY = -2.0f / Vector3::kDivisionEpsilon;
+	assert(std::fabs(scalarResult.x - expectedScalarX) < 1.0f);
+	assert(std::fabs(scalarResult.y - expectedScalarY) < 1.0f);
+
+	Vector3 compoundVector = numerator;
+	compoundVector /= nearZeroDivisor;
+	assert(compoundVector.equals(vectorResult, 1.0f));
+
+	Vector3 compoundScalar = numerator;
+	compoundScalar /= 0.0f;
+	assert(compoundScalar.equals(scalarResult, 1.0f));
+
+	return 0;
+}