Document z_lib Sfx Functions (#1470)

* document lib sfx

* rename functions

8 files changed, 46 insertions, 35 deletions

diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 47bc082c6..aa1f16291 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -489,7 +489,7 @@ void func_8002C7BC(TargetContext* targetCtx, Player* player, Actor* actorArg, Pl
 
             lockOnSfxId = CHECK_FLAG_ALL(actorArg->flags, ACTOR_FLAG_0 | ACTOR_FLAG_2) ? NA_SE_SY_LOCK_ON
                                                                                        : NA_SE_SY_LOCK_ON_HUMAN;
-            func_80078884(lockOnSfxId);
+            Sfx_PlaySfxCentered(lockOnSfxId);
         }
 
         targetCtx->targetCenterPos.x = actorArg->world.pos.x;
@@ -1751,7 +1751,7 @@ void Player_PlaySfx(Player* player, u16 sfxId) {
  * Play a sound effect at the actor's position
  */
 void Actor_PlaySfx(Actor* actor, u16 sfxId) {
-    func_80078914(&actor->projectedPos, sfxId);
+    Sfx_PlaySfxAtPos(&actor->projectedPos, sfxId);
 }
 
 void func_8002F850(PlayState* play, Actor* actor) {
@@ -1767,8 +1767,8 @@ void func_8002F850(PlayState* play, Actor* actor) {
         surfaceSfxOffset = SurfaceType_GetSfxOffset(&play->colCtx, actor->floorPoly, actor->floorBgId);
     }
 
-    func_80078914(&actor->projectedPos, NA_SE_EV_BOMB_BOUND);
-    func_80078914(&actor->projectedPos, NA_SE_PL_WALK_GROUND + surfaceSfxOffset);
+    Sfx_PlaySfxAtPos(&actor->projectedPos, NA_SE_EV_BOMB_BOUND);
+    Sfx_PlaySfxAtPos(&actor->projectedPos, NA_SE_PL_WALK_GROUND + surfaceSfxOffset);
 }
 
 void func_8002F8F0(Actor* actor, u16 sfxId) {
@@ -1965,7 +1965,8 @@ void Actor_DrawFaroresWindPointer(PlayState* play) {
 
         //! @bug One of the conditions for this block checks an entrance index to see if the light ball should draw.
         //! This does not account for the fact that some dungeons have multiple entrances.
-        //! If a dungeon is entered through a different entrance than the one that was saved, the light ball will not draw.
+        //! If a dungeon is entered through a different entrance than the one that was saved, the light ball will not
+        //! draw.
         if ((play->csCtx.state == CS_STATE_IDLE) &&
             (((void)0, gSaveContext.respawn[RESPAWN_MODE_TOP].entranceIndex) ==
              ((void)0, gSaveContext.save.entranceIndex)) &&
@@ -1998,8 +1999,8 @@ void Actor_DrawFaroresWindPointer(PlayState* play) {
             gSPDisplayList(POLY_XLU_DISP++, gEffFlash1DL);
         }
 
-        //! @bug This function call is not contained in the above block, meaning the light for Farore's Wind will draw in 
-        //! every scene at the same position that it was originally set.
+        //! @bug This function call is not contained in the above block, meaning the light for Farore's Wind will draw
+        //! in every scene at the same position that it was originally set.
         Lights_PointNoGlowSetInfo(&D_8015BC00, ((void)0, gSaveContext.respawn[RESPAWN_MODE_TOP].pos.x),
                                   ((void)0, gSaveContext.respawn[RESPAWN_MODE_TOP].pos.y) + yOffset,
                                   ((void)0, gSaveContext.respawn[RESPAWN_MODE_TOP].pos.z), 255, 255, 255, lightRadius);
@@ -2214,7 +2215,7 @@ void Actor_UpdateAll(PlayState* play, ActorContext* actorCtx) {
         actor = NULL;
         if (actorCtx->targetCtx.unk_4B != 0) {
             actorCtx->targetCtx.unk_4B = 0;
-            func_80078884(NA_SE_SY_LOCK_OFF);
+            Sfx_PlaySfxCentered(NA_SE_SY_LOCK_OFF);
         }
     }
 
@@ -2316,13 +2317,13 @@ void func_80030ED8(Actor* actor) {
         Audio_PlaySfxGeneral(actor->sfx, &actor->projectedPos, 4, &gSfxDefaultFreqAndVolScale,
                              &gSfxDefaultFreqAndVolScale, &gSfxDefaultReverb);
     } else if (actor->flags & ACTOR_FLAG_20) {
-        func_80078884(actor->sfx);
+        Sfx_PlaySfxCentered(actor->sfx);
     } else if (actor->flags & ACTOR_FLAG_21) {
-        func_800788CC(actor->sfx);
+        Sfx_PlaySfxCentered2(actor->sfx);
     } else if (actor->flags & ACTOR_FLAG_28) {
         func_800F4C58(&gSfxDefaultPos, NA_SE_SY_TIMER - SFX_FLAG, (s8)(actor->sfx - 1));
     } else {
-        func_80078914(&actor->projectedPos, actor->sfx);
+        Sfx_PlaySfxAtPos(&actor->projectedPos, actor->sfx);
     }
 }
 
diff --git a/src/code/z_camera.c b/src/code/z_camera.c
index 7e6fb10f0..a57155cf3 100644
--- a/src/code/z_camera.c
+++ b/src/code/z_camera.c
@@ -6220,7 +6220,7 @@ s32 Camera_Demo5(Camera* camera) {
 
     framesDiff = sDemo5PrevSfxFrame - camera->play->state.frames;
     if ((framesDiff > 50) || (framesDiff < -50)) {
-        func_80078884((u32)camera->data1);
+        Sfx_PlaySfxCentered((u32)camera->data1);
     }
 
     sDemo5PrevSfxFrame = camera->play->state.frames;
@@ -7456,11 +7456,11 @@ s32 Camera_DbgChangeMode(Camera* camera) {
     if (!gDebugCamEnabled && camera->play->activeCamId == CAM_ID_MAIN) {
         if (CHECK_BTN_ALL(D_8015BD7C->state.input[2].press.button, BTN_CUP)) {
             osSyncPrintf("attention sound URGENCY\n");
-            func_80078884(NA_SE_SY_ATTENTION_URGENCY);
+            Sfx_PlaySfxCentered(NA_SE_SY_ATTENTION_URGENCY);
         }
         if (CHECK_BTN_ALL(D_8015BD7C->state.input[2].press.button, BTN_CDOWN)) {
             osSyncPrintf("attention sound NORMAL\n");
-            func_80078884(NA_SE_SY_ATTENTION_ON);
+            Sfx_PlaySfxCentered(NA_SE_SY_ATTENTION_ON);
         }
 
         if (CHECK_BTN_ALL(D_8015BD7C->state.input[2].press.button, BTN_CRIGHT)) {
@@ -7884,7 +7884,7 @@ s32 Camera_ChangeModeFlags(Camera* camera, s16 mode, u8 flags) {
     if (!((sCameraSettings[camera->setting].unk_00 & 0x3FFFFFFF) & (1 << mode))) {
         if (mode == CAM_MODE_FIRST_PERSON) {
             osSyncPrintf("camera: error sound\n");
-            func_80078884(NA_SE_SY_ERROR);
+            Sfx_PlaySfxCentered(NA_SE_SY_ERROR);
         }
 
         if (camera->mode != CAM_MODE_NORMAL) {
@@ -7972,20 +7972,20 @@ s32 Camera_ChangeModeFlags(Camera* camera, s16 mode, u8 flags) {
         if (camera->status == CAM_STAT_ACTIVE) {
             switch (modeChangeFlags) {
                 case 1:
-                    func_80078884(0);
+                    Sfx_PlaySfxCentered(0);
                     break;
                 case 2:
                     if (camera->play->roomCtx.curRoom.behaviorType1 == ROOM_BEHAVIOR_TYPE1_1) {
-                        func_80078884(NA_SE_SY_ATTENTION_URGENCY);
+                        Sfx_PlaySfxCentered(NA_SE_SY_ATTENTION_URGENCY);
                     } else {
-                        func_80078884(NA_SE_SY_ATTENTION_ON);
+                        Sfx_PlaySfxCentered(NA_SE_SY_ATTENTION_ON);
                     }
                     break;
                 case 4:
-                    func_80078884(NA_SE_SY_ATTENTION_URGENCY);
+                    Sfx_PlaySfxCentered(NA_SE_SY_ATTENTION_URGENCY);
                     break;
                 case 8:
-                    func_80078884(NA_SE_SY_ATTENTION_ON);
+                    Sfx_PlaySfxCentered(NA_SE_SY_ATTENTION_ON);
                     break;
             }
         }
diff --git a/src/code/z_demo.c b/src/code/z_demo.c
index 744ac3a5a..4a85639cf 100644
--- a/src/code/z_demo.c
+++ b/src/code/z_demo.c
@@ -317,7 +317,7 @@ void CutsceneCmd_Misc(PlayState* play, CutsceneContext* csCtx, CsCmdMisc* cmd) {
             }
 
             if (csCtx->curFrame == 783) {
-                func_80078884(NA_SE_EV_DEKU_DEATH);
+                Sfx_PlaySfxCentered(NA_SE_EV_DEKU_DEATH);
             } else if (csCtx->curFrame == 717) {
                 play->roomCtx.unk_74[0] = 0;
             }
@@ -333,7 +333,7 @@ void CutsceneCmd_Misc(PlayState* play, CutsceneContext* csCtx, CsCmdMisc* cmd) {
 
         case CS_MISC_TRIFORCE_FLASH:
             if (play->roomCtx.unk_74[1] == 0) {
-                func_80078884(NA_SE_EV_TRIFORCE_FLASH);
+                Sfx_PlaySfxCentered(NA_SE_EV_TRIFORCE_FLASH);
             }
 
             if (play->roomCtx.unk_74[1] < 255) {
@@ -471,7 +471,7 @@ void CutsceneCmd_Misc(PlayState* play, CutsceneContext* csCtx, CsCmdMisc* cmd) {
                 play->envCtx.sandstormState = SANDSTORM_FILL;
             }
 
-            func_800788CC(NA_SE_EV_SAND_STORM - SFX_FLAG);
+            Sfx_PlaySfxCentered2(NA_SE_EV_SAND_STORM - SFX_FLAG);
             break;
 
         case CS_MISC_SUNSSONG_START:
@@ -1435,7 +1435,7 @@ void CutsceneCmd_Transition(PlayState* play, CutsceneContext* csCtx, CsCmdTransi
                         Audio_PlaySfxGeneral(NA_SE_EV_WHITE_OUT, &gSfxDefaultPos, 4, &gSfxDefaultFreqAndVolScale,
                                              &gSfxDefaultFreqAndVolScale, &gSfxDefaultReverb);
                     } else if ((lerp == 0.0f) && (play->sceneId == SCENE_INSIDE_GANONS_CASTLE)) {
-                        func_800788CC(NA_SE_EV_WHITE_OUT);
+                        Sfx_PlaySfxCentered2(NA_SE_EV_WHITE_OUT);
                     }
                 } else {
                     play->envCtx.screenFillColor[3] = (1.0f - lerp) * 255.0f;
diff --git a/src/code/z_kankyo.c b/src/code/z_kankyo.c
index 9de3f4c25..97e15a6e2 100644
--- a/src/code/z_kankyo.c
+++ b/src/code/z_kankyo.c
@@ -912,10 +912,10 @@ void Environment_Update(PlayState* play, EnvironmentContext* envCtx, LightContex
             // delaying the chicken crow or dog howl sfx by 15 frames when loading the new area.
 
             if (((void)0, gSaveContext.nextDayTime) == (NEXT_TIME_DAY_SET - (15 * 0x10))) {
-                func_80078884(NA_SE_EV_CHICKEN_CRY_M);
+                Sfx_PlaySfxCentered(NA_SE_EV_CHICKEN_CRY_M);
                 gSaveContext.nextDayTime = NEXT_TIME_NONE;
             } else if (((void)0, gSaveContext.nextDayTime) == (NEXT_TIME_NIGHT_SET - (15 * 0x10))) {
-                func_800788CC(NA_SE_EV_DOG_CRY_EVENING);
+                Sfx_PlaySfxCentered2(NA_SE_EV_DOG_CRY_EVENING);
                 gSaveContext.nextDayTime = NEXT_TIME_NONE;
             }
         }
@@ -2122,7 +2122,7 @@ void Environment_PlayTimeBasedSequence(PlayState* play) {
 
         case TIMESEQ_NIGHT_BEGIN_SFX:
             if (gSaveContext.save.dayTime > CLOCK_TIME(18, 0)) {
-                func_800788CC(NA_SE_EV_DOG_CRY_EVENING);
+                Sfx_PlaySfxCentered2(NA_SE_EV_DOG_CRY_EVENING);
                 play->envCtx.timeSeqState++;
             }
             break;
@@ -2158,7 +2158,7 @@ void Environment_PlayTimeBasedSequence(PlayState* play) {
                 gSaveContext.save.totalDays++;
                 gSaveContext.save.bgsDayCount++;
                 gSaveContext.dogIsLost = true;
-                func_80078884(NA_SE_EV_CHICKEN_CRY_M);
+                Sfx_PlaySfxCentered(NA_SE_EV_CHICKEN_CRY_M);
 
                 if ((Inventory_ReplaceItem(play, ITEM_WEIRD_EGG, ITEM_CHICKEN) ||
                      Inventory_ReplaceItem(play, ITEM_POCKET_EGG, ITEM_POCKET_CUCCO)) &&
diff --git a/src/code/z_lib.c b/src/code/z_lib.c
index ac5220ab0..2e00bcd59 100644
--- a/src/code/z_lib.c
+++ b/src/code/z_lib.c
@@ -590,16 +590,26 @@ void Color_RGBA8_Copy(Color_RGBA8* dst, Color_RGBA8* src) {
     dst->a = src->a;
 }
 
-void func_80078884(u16 sfxId) {
+/**
+ * Play a sound effect at the center of the screen.
+ */
+void Sfx_PlaySfxCentered(u16 sfxId) {
     Audio_PlaySfxGeneral(sfxId, &gSfxDefaultPos, 4, &gSfxDefaultFreqAndVolScale, &gSfxDefaultFreqAndVolScale,
                          &gSfxDefaultReverb);
 }
 
-void func_800788CC(u16 sfxId) {
+/**
+ * Play a sound effect at the center of the screen. Identical to `Sfx_PlaySfxCentered`.
+ */
+void Sfx_PlaySfxCentered2(u16 sfxId) {
     Audio_PlaySfxGeneral(sfxId, &gSfxDefaultPos, 4, &gSfxDefaultFreqAndVolScale, &gSfxDefaultFreqAndVolScale,
                          &gSfxDefaultReverb);
 }
 
-void func_80078914(Vec3f* arg0, u16 sfxId) {
-    Audio_PlaySfxGeneral(sfxId, arg0, 4, &gSfxDefaultFreqAndVolScale, &gSfxDefaultFreqAndVolScale, &gSfxDefaultReverb);
+/**
+ * Play a sound effect at the requested position.
+ */
+void Sfx_PlaySfxAtPos(Vec3f* projectedPos, u16 sfxId) {
+    Audio_PlaySfxGeneral(sfxId, projectedPos, 4, &gSfxDefaultFreqAndVolScale, &gSfxDefaultFreqAndVolScale,
+                         &gSfxDefaultReverb);
 }
diff --git a/src/code/z_lifemeter.c b/src/code/z_lifemeter.c
index 8f1f07e35..a1f04093b 100644
--- a/src/code/z_lifemeter.c
+++ b/src/code/z_lifemeter.c
@@ -508,7 +508,7 @@ void Health_UpdateBeatingHeart(PlayState* play) {
             interfaceCtx->beatingHeartOscillatorDirection = 0;
             if (!Player_InCsMode(play) && (play->pauseCtx.state == 0) && (play->pauseCtx.debugState == 0) &&
                 Health_IsCritical() && !Play_InCsMode(play)) {
-                func_80078884(NA_SE_SY_HITPOINT_ALARM);
+                Sfx_PlaySfxCentered(NA_SE_SY_HITPOINT_ALARM);
             }
         }
     } else {
diff --git a/src/code/z_onepointdemo.c b/src/code/z_onepointdemo.c
index cfe61236f..61548559a 100644
--- a/src/code/z_onepointdemo.c
+++ b/src/code/z_onepointdemo.c
@@ -489,7 +489,7 @@ s32 OnePointCutscene_SetInfo(PlayState* play, s16 subCamId, s16 csId, Actor* act
             Play_ChangeCameraSetting(play, subCamId, CAM_SET_CS_3);
             func_8002DF54(play, &player->actor, PLAYER_CSMODE_5);
             OnePointCutscene_SetCsCamPoints(subCam, D_80120304 | 0x2000, D_80120300, D_8012013C, D_8012021C);
-            func_80078884(NA_SE_SY_CORRECT_CHIME);
+            Sfx_PlaySfxCentered(NA_SE_SY_CORRECT_CHIME);
             OnePointCutscene_Vec3sToVec3f(&mainCam->at, &D_8012013C[D_801202FC - 2].pos);
             OnePointCutscene_Vec3sToVec3f(&mainCam->eye, &D_8012021C[D_801202FC - 2].pos);
             D_8012013C[D_801202FC - 3].pos.x +=
diff --git a/src/code/z_play.c b/src/code/z_play.c
index 2a5727d2f..4e3a7b286 100644
--- a/src/code/z_play.c
+++ b/src/code/z_play.c
@@ -332,7 +332,7 @@ void Play_Init(GameState* thisx) {
         gSaveContext.sceneLayer == 6) {
         osSyncPrintf("エンディングはじまるよー\n"); // "The ending starts"
         ((void (*)(void))0x81000000)();
-        osSyncPrintf("出戻り？\n");                 // "Return?"
+        osSyncPrintf("出戻り？\n"); // "Return?"
     }
 
     Cutscene_HandleEntranceTriggers(this);