Merge pull request #7157 from Baezon/uvec-dominant-frame-of-ref

Uvec dominant frame of ref for submodels

Author: Goober5000

code/math/vecmat.cpp

@@ -832,26 +832,38 @@ void vm_vector_2_matrix_gen_vectors(matrix *m)
 	}
 }
 
-matrix *vm_vector_2_matrix(matrix *m, const vec3d *fvec, const vec3d *uvec, const vec3d *rvec)
+/**
+ * @brief Generates a matrix from a normalized uvec.
+ *
+ * @param[in,out] matrix The matrix to generate
+ *
+ * @details The matrix's uvec is used to generate the fvec and rvec
+ *
+ * @sa vm_vector_2_matrix_uvec(), vm_vector_2_matrix_uvec_norm()
+ */
+void vm_vector_2_matrix_gen_vectors_uvec(matrix* m)
 {
-	vec3d fvec_norm;
-	vm_vec_copy_normalize(&fvec_norm, fvec);
-	fvec = &fvec_norm;
+	vec3d* xvec = &m->vec.rvec;
+	vec3d* yvec = &m->vec.uvec;
+	vec3d* zvec = &m->vec.fvec;
 
-	vec3d uvec_norm;
-	if (uvec != nullptr) {
-		vm_vec_copy_normalize(&uvec_norm, uvec);
-		uvec = &uvec_norm;
-	}
+	if ((yvec->xyz.x == 0.0f) && (yvec->xyz.z == 0.0f)) {		// vec is straight up or down
+		m->vec.rvec.xyz.x = 1.0f;
+		m->vec.fvec.xyz.z = (yvec->xyz.y > 0.0f) ? 1.0f : -1.0f;
 
-	vec3d rvec_norm;
-	if (rvec != nullptr) {
-		vm_vec_copy_normalize(&rvec_norm, rvec);
-		rvec = &rvec_norm;
+		m->vec.rvec.xyz.y = m->vec.rvec.xyz.z = m->vec.fvec.xyz.x = m->vec.fvec.xyz.y = 0.0f;
 	}
+	else { 		//not straight up or down
 
-	// Call the actuall function for normalized vectors
-	return vm_vector_2_matrix_norm(m, fvec, uvec, rvec);
+		xvec->xyz.x = yvec->xyz.y;
+		xvec->xyz.y = 0.0f;
+		xvec->xyz.z = -yvec->xyz.x;
+
+		vm_vec_normalize(xvec);
+
+		vm_vec_cross(zvec, xvec, yvec);
+
+	}
 }
 
 matrix *vm_vector_2_matrix_norm(matrix *m, const vec3d *fvec, const vec3d *uvec, const vec3d *rvec)
@@ -915,6 +927,117 @@ matrix *vm_vector_2_matrix_norm(matrix *m, const vec3d *fvec, const vec3d *uvec,
 	return m;
 }
 
+matrix* vm_vector_2_matrix_uvec_norm(matrix* m, const vec3d* fvec, const vec3d* uvec, const vec3d* rvec)
+{
+
+	// sanity
+	Assertion(fvec == nullptr || vm_vec_is_normalized(fvec), "if fvec is provided, it must be normalized!");
+	Assertion(uvec == nullptr || vm_vec_is_normalized(uvec), "if uvec is provided, it must be normalized!");
+	Assertion(rvec == nullptr || vm_vec_is_normalized(rvec), "if rvec is provided, it must be normalized!");
+	Assertion(fvec != nullptr || uvec != nullptr, "vm_vector_2_matrix_uvec_norm requires one of fvec or uvec!");
+
+	matrix temp = vmd_identity_matrix;
+
+	vec3d* xvec = &temp.vec.rvec;
+	vec3d* yvec = &temp.vec.uvec;
+	vec3d* zvec = &temp.vec.fvec;
+
+	if (uvec != nullptr) { // use up vec as the 'primary'
+		*yvec = *uvec;
+		if (rvec == nullptr && fvec == nullptr) {     //only up vec
+			vm_vector_2_matrix_gen_vectors_uvec(&temp);
+		}
+		else if (fvec != nullptr){                      //use fwd vec
+			*zvec = *fvec;
+
+			vm_vec_cross(xvec, yvec, zvec);
+
+			//normalize new perpendicular vector
+			vm_vec_normalize(xvec);
+
+			//now recompute fwd vector, in case it wasn't entirely perpendiclar
+			vm_vec_cross(zvec, xvec, yvec);
+		} else { // else use rvec
+			*xvec = *rvec;
+
+			vm_vec_cross(zvec, xvec, yvec);
+
+			//normalize new perpendicular vector
+			vm_vec_normalize(zvec);
+
+			//now recompute right vector, in case it wasn't entirely perpendiclar
+			vm_vec_cross(xvec, yvec, zvec);
+		}
+	}
+	else if (fvec != nullptr) {      //use fwd vec as the 'primary'
+		*zvec = *fvec;
+
+		if (rvec != nullptr) { // use rvec
+			vm_vec_cross(yvec, zvec, xvec);
+
+			//normalize new perpendicular vector
+			vm_vec_normalize(yvec);
+
+			//now recompute right vector, in case it wasn't entirely perpendiclar
+			vm_vec_cross(xvec, yvec, zvec);
+		} else { // only fwd vec
+			vm_vector_2_matrix_gen_vectors(&temp);
+		}
+	}
+
+	// Copy the computed values into the output parameter
+	*m = temp;
+	return m;
+}
+
+matrix *vm_vector_2_matrix(matrix *m, const vec3d *fvec, const vec3d *uvec, const vec3d *rvec)
+{
+	vec3d fvec_norm;
+	if (fvec != nullptr) {
+		vm_vec_copy_normalize(&fvec_norm, fvec);
+		fvec = &fvec_norm;
+	}
+
+	vec3d uvec_norm;
+	if (uvec != nullptr) {
+		vm_vec_copy_normalize(&uvec_norm, uvec);
+		uvec = &uvec_norm;
+	}
+
+	vec3d rvec_norm;
+	if (rvec != nullptr) {
+		vm_vec_copy_normalize(&rvec_norm, rvec);
+		rvec = &rvec_norm;
+	}
+
+	// Call the actuall function for normalized vectors
+	return vm_vector_2_matrix_norm(m, fvec, uvec, rvec);
+}
+
+matrix* vm_vector_2_matrix_uvec(matrix* m, const vec3d* fvec, const vec3d* uvec, const vec3d* rvec)
+{
+	vec3d fvec_norm;
+	if (fvec != nullptr) {
+		vm_vec_copy_normalize(&fvec_norm, fvec);
+		fvec = &fvec_norm;
+	}
+
+	vec3d uvec_norm;
+	if (uvec != nullptr) {
+		vm_vec_copy_normalize(&uvec_norm, uvec);
+		uvec = &uvec_norm;
+	}
+
+	vec3d rvec_norm;
+	if (rvec != nullptr) {
+		vm_vec_copy_normalize(&rvec_norm, rvec);
+		rvec = &rvec_norm;
+	}
+
+	// Call the actuall function for normalized vectors
+	return vm_vector_2_matrix_uvec_norm(m, fvec, uvec, rvec);
+}
+
 
 // rotates a vector through a matrix, writes to *dest and returns the pointer
 // if m is a rotation matrix it will preserve the length of *src, so normalised vectors will remain normalised

code/math/vecmat.h

@@ -307,6 +307,25 @@ matrix *vm_vec_ang_2_matrix(matrix *m, const vec3d *v, float a);
 matrix *vm_vector_2_matrix(matrix *m, const vec3d *fvec, const vec3d *uvec = nullptr, const vec3d *rvec = nullptr);
 
 
+/**
+ * @brief Generates a matrix from one or more vectors
+ *
+ * @param[out] matrix The generated matrix. Does not need to be an Identity matrix
+ * @param[in] fvec Vector referencing the forward direction (optional)
+ * @param[in] uvec Vector referencing the up direction (Optional)
+ * @param[in] rvec Vector referencing the right-hand direction (Optional)
+ *
+ * @returns Pointer to the generated matrix
+ *
+ * @note THIS FUCNTION SHOULD ONLY BE USED BY MODEL READING
+ *		 in all other situations, the 'forward dominant' version vm_vector_2_matrix should be used
+ * @note All vectors are optional, but at least one of fvec and uvec must be provided
+ *
+ * @sa vm_vector_2_matrix_uvec_norm
+ */
+matrix* vm_vector_2_matrix_uvec(matrix* m, const vec3d* fvec = nullptr, const vec3d* uvec = nullptr, const vec3d* rvec = nullptr);
+
+
 /**
  * @brief Generates a matrix from one or more normalized vectors
  *

code/model/modelread.cpp

@@ -2086,18 +2086,18 @@ modelread_status read_model_file_no_subsys(polymodel * pm, const char* filename,
 						}
 					}
 
-					// make a matrix if we have at least the fvec
-					if (has_fvec)
+					// make a matrix if we have at least the fvec or uvec
+					if (has_fvec || has_uvec)
 					{
-						vm_vector_2_matrix(&sm->frame_of_reference, &fvec, has_uvec ? &uvec : nullptr, has_rvec ? &rvec : nullptr);
+						vm_vector_2_matrix_uvec(&sm->frame_of_reference, has_fvec ? &fvec : nullptr, has_uvec ? &uvec : nullptr, has_rvec ? &rvec : nullptr);
 
 						// if the look_at_offset is still the default value (hasn't been set by submodel properties), assume that
 						// by specifying the submodel orientation matrix we are also specifying the "looking" direction
 						if (sm->look_at_offset == -1.0f)
 							sm->look_at_offset = 0.0f;
 					}
-					else if (has_uvec || has_rvec)
-						Warning(LOCATION, "Improper custom orientation matrix for subsystem %s; you must define an $fvec", sm->name);
+					else if (has_rvec)
+						Warning(LOCATION, "Improper custom orientation matrix for subsystem %s; you must define an $fvec or $uvec", sm->name);
 				}
 
 				{