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: Small `Math_Vec3f_Yaw` doc (#1433)

* Small `Math_Vec3f_Yaw` doc

* remove actor from arg names

---------

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

(limited to 'src/code')

diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index d0b7607e2..73793558a 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 fbea9dce4..cc665fd0c 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 b8e3c2cba..41834bace 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) {
-- 
cgit v1.2.3