From 5e406f754e490e9f815fe7ca2fc36c10fc909624 Mon Sep 17 00:00:00 2001
From: Dragorn421 <Dragorn421@users.noreply.github.com>
Date: Thu, 18 Jan 2024 23:56:54 +0100
Subject: [PATCH] Small `Math_Vec3f_Yaw` doc (#1433)

* Small `Math_Vec3f_Yaw` doc

* remove actor from arg names

---------

Co-authored-by: fig02 <fig02srl@gmail.com>
---
 include/functions.h       |  7 ++++---
 src/code/z_actor.c        | 21 +++++++++++++++------
 src/code/z_lib.c          | 11 ++++++++---
 src/code/z_onepointdemo.c |  7 +++++--
 4 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/include/functions.h b/include/functions.h
index 7e9cc99ac5..29ddbfca8a 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -354,8 +354,9 @@ void Actor_MoveXZGravity(Actor* actor);
 void Actor_UpdateVelocityXYZ(Actor* actor);
 void Actor_MoveXYZ(Actor* actor);
 void Actor_SetProjectileSpeed(Actor* actor, f32 speedXYZ);
-s16 Actor_WorldYawTowardActor(Actor* actorA, Actor* actorB);
-s16 Actor_WorldYawTowardPoint(Actor* actor, Vec3f* refPoint);
+s16 Actor_WorldYawTowardActor(Actor* origin, Actor* target);
+s16 Actor_FocusYawTowardActor(Actor* origin, Actor* target);
+s16 Actor_WorldYawTowardPoint(Actor* origin, Vec3f* point);
 f32 Actor_WorldDistXYZToActor(Actor* actorA, Actor* actorB);
 f32 Actor_WorldDistXYZToPoint(Actor* actor, Vec3f* refPoint);
 s16 Actor_WorldPitchTowardActor(Actor* actorA, Actor* actorB);
@@ -856,7 +857,7 @@ void Math_Vec3f_Scale(Vec3f* vec, f32 scaleF);
 f32 Math_Vec3f_DistXYZ(Vec3f* a, Vec3f* b);
 f32 Math_Vec3f_DistXYZAndStoreDiff(Vec3f* a, Vec3f* b, Vec3f* dest);
 f32 Math_Vec3f_DistXZ(Vec3f* a, Vec3f* b);
-s16 Math_Vec3f_Yaw(Vec3f* a, Vec3f* b);
+s16 Math_Vec3f_Yaw(Vec3f* origin, Vec3f* point);
 s16 Math_Vec3f_Pitch(Vec3f* a, Vec3f* b);
 void Actor_ProcessInitChain(Actor* actor, InitChainEntry* ichain);
 f32 Math_SmoothStepToF(f32* pValue, f32 target, f32 fraction, f32 step, f32 minStep);
diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index d0b7607e21..73793558af 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -915,16 +915,25 @@ void Actor_UpdatePosByAnimation(Actor* actor, SkelAnime* skelAnime) {
     actor->world.pos.z += posDiff.z * actor->scale.z;
 }
 
-s16 Actor_WorldYawTowardActor(Actor* actorA, Actor* actorB) {
-    return Math_Vec3f_Yaw(&actorA->world.pos, &actorB->world.pos);
+/**
+ * @return Yaw towards `target` for `origin`, using world positions.
+ */
+s16 Actor_WorldYawTowardActor(Actor* origin, Actor* target) {
+    return Math_Vec3f_Yaw(&origin->world.pos, &target->world.pos);
 }
 
-s16 Actor_FocusYawTowardActor(Actor* actorA, Actor* actorB) {
-    return Math_Vec3f_Yaw(&actorA->focus.pos, &actorB->focus.pos);
+/**
+ * @return Yaw towards `target` for `origin`, using focus positions.
+ */
+s16 Actor_FocusYawTowardActor(Actor* origin, Actor* target) {
+    return Math_Vec3f_Yaw(&origin->focus.pos, &target->focus.pos);
 }
 
-s16 Actor_WorldYawTowardPoint(Actor* actor, Vec3f* refPoint) {
-    return Math_Vec3f_Yaw(&actor->world.pos, refPoint);
+/**
+ * @return Yaw towards `point` for `origin`.
+ */
+s16 Actor_WorldYawTowardPoint(Actor* origin, Vec3f* point) {
+    return Math_Vec3f_Yaw(&origin->world.pos, point);
 }
 
 s16 Actor_WorldPitchTowardActor(Actor* actorA, Actor* actorB) {
diff --git a/src/code/z_lib.c b/src/code/z_lib.c
index fbea9dce45..cc665fd0c7 100644
--- a/src/code/z_lib.c
+++ b/src/code/z_lib.c
@@ -300,9 +300,14 @@ f32 Math_Vec3f_DiffY(Vec3f* a, Vec3f* b) {
     return b->y - a->y;
 }
 
-s16 Math_Vec3f_Yaw(Vec3f* a, Vec3f* b) {
-    f32 dx = b->x - a->x;
-    f32 dz = b->z - a->z;
+/**
+ * @param origin Position of the origin, the location from which to look at the target `point`
+ * @param point Position of the target point, in the same space as `origin`
+ * @return The yaw towards `point` when at `origin`, assuming +z is forwards.
+ */
+s16 Math_Vec3f_Yaw(Vec3f* origin, Vec3f* point) {
+    f32 dx = point->x - origin->x;
+    f32 dz = point->z - origin->z;
 
     return Math_Atan2S(dz, dx);
 }
diff --git a/src/code/z_onepointdemo.c b/src/code/z_onepointdemo.c
index b8e3c2cba8..41834bacec 100644
--- a/src/code/z_onepointdemo.c
+++ b/src/code/z_onepointdemo.c
@@ -20,8 +20,11 @@ Vec3f OnePointCutscene_AddVecGeoToVec3f(Vec3f* a, VecGeo* geo) {
     return sum;
 }
 
-s16 OnePointCutscene_Vec3fYaw(Vec3f* vec1, Vec3f* vec2) {
-    return CAM_DEG_TO_BINANG(RAD_TO_DEG(Math_FAtan2F(vec2->x - vec1->x, vec2->z - vec1->z)));
+/**
+ * @see Math_Vec3f_Yaw
+ */
+s16 OnePointCutscene_Vec3fYaw(Vec3f* origin, Vec3f* point) {
+    return CAM_DEG_TO_BINANG(RAD_TO_DEG(Math_FAtan2F(point->x - origin->x, point->z - origin->z)));
 }
 
 void OnePointCutscene_Vec3sToVec3f(Vec3f* src, Vec3s* dst) {