More Camera Flags (#1453)

* Generic Camera Flags

* New flag names

* Add flags to functions

* Finish flag docs

* More docs

* More cleanup

* More clarity

* Better shrinkwindow flag docs

* Improve name

* CAM_INTERFACE_FLAGS

* Better approach to edge cases

* Change ordering for consistency

* Oops

* Add masks to macro

* PR/Discord discussions

* cleanup comment

* Oops

* PR Suggestions

* More PR Feedback

* More PR Suggestions

* More Camera Flags

* PR Suggestions

* More flag style change

* Small cleanup

* More flag docs

* Another flag

* Fix flags

* sync names with other PRs

* more fixes

* fix comments

* update with hud visibility mode docs

* missed one

* fix comments

* Roman PR Suggestions

* interfaceField

* small fix

* letterbox cleanup

* cleanup

* fix macro arg

* fix func declaration

* many more docs

* better docs?

* missed some

* oops, revert

* add flags to name

* cleanup

* flag

* double signal

* simplify cam func name

* more suggestions

* PR Suggestion

2 files changed, 27 insertions, 27 deletions

diff --git a/include/functions.h b/include/functions.h
index 771b66602..011d0d0c2 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -634,10 +634,10 @@ void Camera_InitDataUsingPlayer(Camera* camera, Player* player);
 s16 Camera_ChangeStatus(Camera* camera, s16 status);
 Vec3s Camera_Update(Camera* camera);
 void Camera_Finish(Camera* camera);
-s32 Camera_ChangeMode(Camera* camera, s16 mode);
+s32 Camera_RequestMode(Camera* camera, s16 mode);
 s32 Camera_CheckValidMode(Camera* camera, s16 mode);
-s32 Camera_ChangeSetting(Camera* camera, s16 setting);
-s32 Camera_ChangeBgCamIndex(Camera* camera, s32 bgCamIndex);
+s32 Camera_RequestSetting(Camera* camera, s16 setting);
+s32 Camera_RequestBgCam(Camera* camera, s32 requestedBgCamIndex);
 s16 Camera_GetInputDirYaw(Camera* camera);
 Vec3s* Camera_GetCamDir(Vec3s* dst, Camera* camera);
 s16 Camera_GetCamDirPitch(Camera* camera);
@@ -657,7 +657,7 @@ Vec3f* Camera_GetQuakeOffset(Vec3f* quakeOffset, Camera* camera);
 void Camera_SetCameraData(Camera* camera, s16 setDataFlags, void* data0, void* data1, s16 data2, s16 data3,
                           UNK_TYPE arg6);
 s32 func_8005B198(void);
-s16 func_8005B1A4(Camera* camera);
+s16 Camera_SetFinishedFlag(Camera* camera);
 DamageTable* DamageTable_Get(s32 index);
 void DamageTable_Clear(DamageTable* table);
 void Collider_DrawRedPoly(GraphicsContext* gfxCtx, Vec3f* vA, Vec3f* vB, Vec3f* vC);
@@ -1271,7 +1271,7 @@ s32 Play_SetCameraFov(PlayState* this, s16 camId, f32 fov);
 s32 Play_SetCameraRoll(PlayState* this, s16 camId, s16 roll);
 void Play_CopyCamera(PlayState* this, s16 destCamId, s16 srcCamId);
 s32 Play_InitCameraDataUsingPlayer(PlayState* this, s16 camId, Player* player, s16 setting);
-s32 Play_ChangeCameraSetting(PlayState* this, s16 camId, s16 setting);
+s32 Play_RequestCameraSetting(PlayState* this, s16 camId, s16 setting);
 void Play_ReturnToMainCam(PlayState* this, s16 camId, s16 duration);
 void Play_SaveSceneFlags(PlayState* this);
 void Play_SetupRespawnPoint(PlayState* this, s32 respawnMode, s32 playerParams);
diff --git a/include/z64camera.h b/include/z64camera.h
index f6c458918..81584c1b6 100644
--- a/include/z64camera.h
+++ b/include/z64camera.h
@@ -84,33 +84,33 @@
 #define CAM_INTERFACE_FIELD(letterboxFlag, hudVisibilityMode, funcFlags) \
     (((letterboxFlag) & CAM_LETTERBOX_MASK) | CAM_HUD_VISIBILITY(hudVisibilityMode) | ((funcFlags) & 0xFF))
 
-// Camera behaviorFlags. Flags specifically for settings, modes, and bgCam
-// Used to store current state, only CAM_BEHAVIOR_SETTING_1 and CAM_BEHAVIOR_BG_2 are read from and used in logic
+// Camera behaviorFlags. Flags specifically for settings, modes, and bgCam. Reset every frame.
+// Used to store current state, only CAM_BEHAVIOR_SETTING_CHECK_PRIORITY and CAM_BEHAVIOR_BG_PROCESSED are read from and used in logic
 // Setting (0x1, 0x10)
-#define CAM_BEHAVIOR_SETTING_1 (1 << 0)
-#define CAM_BEHAVIOR_SETTING_2 (1 << 4)
+#define CAM_BEHAVIOR_SETTING_CHECK_PRIORITY (1 << 0)
+#define CAM_BEHAVIOR_SETTING_VALID (1 << 4) // Set when a valid camera setting is requested
 // Mode (0x2, 0x20)
-#define CAM_BEHAVIOR_MODE_1 (1 << 1)
-#define CAM_BEHAVIOR_MODE_2 (1 << 5)
+#define CAM_BEHAVIOR_MODE_SUCCESS (1 << 1) // Set when the camera mode is the requested mode
+#define CAM_BEHAVIOR_MODE_VALID (1 << 5) // Set when a valid camera mode is requested
 // bgCam (0x4, 0x40)
-#define CAM_BEHAVIOR_BG_1 (1 << 2)
-#define CAM_BEHAVIOR_BG_2 (1 << 6)
+#define CAM_BEHAVIOR_BG_SUCCESS (1 << 2)
+#define CAM_BEHAVIOR_BG_PROCESSED (1 << 6)
 
 // Camera stateFlags. Variety of generic flags
-#define CAM_STATE_0 (1 << 0) // Must be set for the camera to change settings based on the bg surface
-#define CAM_STATE_1 (1 << 1) // Must be set for Camera_UpdateWater to run
-#define CAM_STATE_2 (1 << 2)
-#define CAM_STATE_3 (1 << 3) // Customizable flag for different functions
-#define CAM_STATE_4 (1 << 4)
-#define CAM_STATE_5 (1 << 5)
-#define CAM_STATE_6 (1 << 6)
-#define CAM_STATE_7 (1 << 7) // Set in play, unused
-#define CAM_STATE_8 (1 << 8) // Camera (eye) is underwater
-#define CAM_STATE_9 (1 << 9)
-#define CAM_STATE_10 (1 << 10) // Prevents the camera from changing settings based on the bg surface
-#define CAM_STATE_12 (1 << 12) // Set in Camera_Demo7, but Camera_Demo7 is never called
-#define CAM_STATE_14 (1 << 14) // isInitialized. Turned on in Camera Init, never used or changed
-#define CAM_STATE_15 ((s16)(1 << 15))
+#define CAM_STATE_CHECK_BG_ALT (1 << 0) // Must be set for the camera to change settings based on the bg surface
+#define CAM_STATE_CHECK_WATER (1 << 1) // Must be set for Camera_UpdateWater to run
+#define CAM_STATE_CHECK_BG (1 << 2) //  Must be set for the camera to change settings based on the bg surface
+#define CAM_STATE_EXTERNAL_FINISHED (1 << 3) // Signal from the external systems to camera that the current cam-update function is no longer needed
+#define CAM_STATE_CAM_FUNC_FINISH (1 << 4) // Signal from camera to player that the cam-update function is finished its primary purpose
+#define CAM_STATE_LOCK_MODE (1 << 5) // Prevents camera from changing mode, unless overriden by `forceModeChange` passed to `Camera_RequestModeImpl`
+#define CAM_STATE_DISTORTION (1 << 6) // Set when camera distortion is on
+#define CAM_STATE_PLAY_INIT (1 << 7) // Set in Play_Init, never used or changed
+#define CAM_STATE_CAMERA_IN_WATER (1 << 8) // Camera (eye) is underwater
+#define CAM_STATE_PLAYER_IN_WATER (1 << 9) // Player is swimming in water
+#define CAM_STATE_BLOCK_BG (1 << 10) // Prevents the camera from changing settings based on the bg surface for 1 frame
+#define CAM_STATE_DEMO7 (1 << 12) // Set in Camera_Demo7, but this function is never called
+#define CAM_STATE_CAM_INIT (1 << 14) // Set in Camera_Init, never used or changed
+#define CAM_STATE_PLAYER_DIVING ((s16)(1 << 15)) // Diving from the surface of the water down
 
 // Camera viewFlags. Set params related to view
 #define CAM_VIEW_AT (1 << 0) // camera->at