Decompile/Document bgCam and actorCsCam (combination of Camera/BgCheck/Play) (#932)

* Document bgCam and actorCsCam

* index

* Small PR suggestions

* small suggestions

* player stateflags

* Fix bss

* Fix BSS

* Fix bss

* Fix bss

src/code/z_bgcheck.c

@@ -3962,8 +3962,8 @@ void CollisionHeader_SegmentedToVirtual(CollisionHeader* colHeader) {
     if (colHeader->surfaceTypeList) {
         colHeader->surfaceTypeList = Lib_SegmentedToVirtual(colHeader->surfaceTypeList);
     }
-    if (colHeader->cameraDataList) {
-        colHeader->cameraDataList = Lib_SegmentedToVirtual(colHeader->cameraDataList);
+    if (colHeader->bgCamList) {
+        colHeader->bgCamList = Lib_SegmentedToVirtual(colHeader->bgCamList);
     }
     if (colHeader->waterBoxes) {
         colHeader->waterBoxes = Lib_SegmentedToVirtual(colHeader->waterBoxes);
@@ -4026,128 +4026,142 @@ u32 SurfaceType_GetData(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId,
 }
 
 /**
- * SurfaceType return CamData Index
+ * SurfaceType get index of bgCam
  */
-u32 SurfaceType_GetCamDataIndex(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
+u32 SurfaceType_GetBgCamIndex(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
     return SurfaceType_GetData(colCtx, poly, bgId, 0) & 0xFF;
 }
 
 /**
- * CamData return camera setting
+ * BgCam get setting of bgCam
  */
-u16 func_800C9728(CollisionContext* colCtx, u32 camId, s32 bgId) {
-    u16 result;
+u16 BgCheck_GetBgCamSettingImpl(CollisionContext* colCtx, u32 bgCamIndex, s32 bgId) {
+    u16 camSetting;
     CollisionHeader* colHeader;
-    CamData* camData;
+    BgCamInfo* bgCamList;
 
     colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
     if (colHeader == NULL) {
-        return 0;
+        return CAM_SET_NONE;
     }
-    camData = colHeader->cameraDataList;
-    result = camData[camId].setting;
-    return result;
+
+    bgCamList = colHeader->bgCamList;
+    camSetting = bgCamList[bgCamIndex].setting;
+
+    return camSetting;
 }
 
 /**
- * SurfaceType return camera setting
+ * BgCam Get the camera setting of bgCam
  */
-u16 SurfaceType_GetCameraSetting(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
+u16 BgCheck_GetBgCamSetting(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
     CollisionHeader* colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
-    CamData* camData;
+    BgCamInfo* bgCamList;
+    SurfaceType* surfaceTypes;
+
+    if (colHeader == NULL) {
+        return CAM_SET_NONE;
+    }
+
+    bgCamList = colHeader->bgCamList;
+    if (bgCamList == NULL) {
+        return CAM_SET_NONE;
+    }
+
+    surfaceTypes = colHeader->surfaceTypeList;
+    if (surfaceTypes == NULL) {
+        return CAM_SET_NONE;
+    }
+
+    return BgCheck_GetBgCamSettingImpl(colCtx, SurfaceType_GetBgCamIndex(colCtx, poly, bgId), bgId);
+}
+
+/**
+ * BgCam Get the total count of Vec3s data from bgCamFuncData
+ */
+u16 BgCheck_GetBgCamCountImpl(CollisionContext* colCtx, u32 bgCamIndex, s32 bgId) {
+    CollisionHeader* colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
+    BgCamInfo* bgCamList;
+
+    if (colHeader == NULL) {
+        return 0;
+    }
+
+    bgCamList = colHeader->bgCamList;
+    if (bgCamList == NULL) {
+        return 0;
+    }
+
+    return bgCamList[bgCamIndex].count;
+}
+
+/**
+ * BgCam Get the total count of Vec3s data from bgCamFuncData
+ */
+u16 BgCheck_GetBgCamCount(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
+    CollisionHeader* colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
+    BgCamInfo* bgCamList;
     SurfaceType* surfaceTypes;
 
     if (colHeader == NULL) {
         return 0;
     }
-    camData = colHeader->cameraDataList;
-    if (camData == NULL) {
+
+    bgCamList = colHeader->bgCamList;
+    if (bgCamList == NULL) {
         return 0;
     }
+
     surfaceTypes = colHeader->surfaceTypeList;
     if (surfaceTypes == NULL) {
         return 0;
     }
-    return func_800C9728(colCtx, SurfaceType_GetCamDataIndex(colCtx, poly, bgId), bgId);
+
+    return BgCheck_GetBgCamCountImpl(colCtx, SurfaceType_GetBgCamIndex(colCtx, poly, bgId), bgId);
 }
 
 /**
- * CamData get number of camera data blocks
+ * BgCam Get Vec3s data from bgCamFuncData
  */
-u16 func_800C97F8(CollisionContext* colCtx, u32 camId, s32 bgId) {
+Vec3s* BgCheck_GetBgCamFuncDataImpl(CollisionContext* colCtx, s32 bgCamIndex, s32 bgId) {
     CollisionHeader* colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
-    CamData* camData;
-
-    if (colHeader == NULL) {
-        return 0;
-    }
-
-    camData = colHeader->cameraDataList;
-    if (camData == NULL) {
-        return 0;
-    }
-    return camData[camId].numData;
-}
-
-/**
- * SurfaceType get number of camera data blocks
- */
-u16 func_800C9844(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
-    CollisionHeader* colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
-    CamData* camData;
-    SurfaceType* surfaceTypes;
-
-    if (colHeader == NULL) {
-        return 0;
-    }
-    camData = colHeader->cameraDataList;
-    if (camData == NULL) {
-        return 0;
-    }
-    surfaceTypes = colHeader->surfaceTypeList;
-    if (surfaceTypes == NULL) {
-        return 0;
-    }
-    return func_800C97F8(colCtx, SurfaceType_GetCamDataIndex(colCtx, poly, bgId), bgId);
-}
-
-/**
- * CamData get data
- */
-Vec3s* func_800C98CC(CollisionContext* colCtx, s32 camId, s32 bgId) {
-    CollisionHeader* colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
-    CamData* cameraDataList;
+    BgCamInfo* bgCamList;
 
     if (colHeader == NULL) {
         return NULL;
     }
-    cameraDataList = colHeader->cameraDataList;
-    if (cameraDataList == NULL) {
+
+    bgCamList = colHeader->bgCamList;
+    if (bgCamList == NULL) {
         return NULL;
     }
-    return Lib_SegmentedToVirtual(cameraDataList[camId].data);
+
+    return Lib_SegmentedToVirtual(bgCamList[bgCamIndex].bgCamFuncData);
 }
 
 /**
- * SurfaceType Get data
+ * BgCam Get Vec3s data from bgCamFuncData
  */
-Vec3s* SurfaceType_GetCamPosData(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
+Vec3s* BgCheck_GetBgCamFuncData(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
     CollisionHeader* colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
-    CamData* camData;
+    BgCamInfo* bgCamList;
     SurfaceType* surfaceTypes;
 
     if (colHeader == NULL) {
         return NULL;
     }
-    camData = colHeader->cameraDataList;
-    if (camData == NULL) {
+
+    bgCamList = colHeader->bgCamList;
+    if (bgCamList == NULL) {
         return NULL;
     }
+
     surfaceTypes = colHeader->surfaceTypeList;
     if (surfaceTypes == NULL) {
         return NULL;
     }
-    return func_800C98CC(colCtx, SurfaceType_GetCamDataIndex(colCtx, poly, bgId), bgId);
+
+    return BgCheck_GetBgCamFuncDataImpl(colCtx, SurfaceType_GetBgCamIndex(colCtx, poly, bgId), bgId);
 }
 
 /**
@@ -4541,41 +4555,46 @@ f32 func_800CA568(CollisionContext* colCtx, s32 waterBoxId, s32 bgId) {
 }
 
 /**
- * WaterBox get CamData index
+ * WaterBox get BgCam index
  */
-u32 WaterBox_GetCamDataIndex(CollisionContext* colCtx, WaterBox* waterBox) {
+u32 WaterBox_GetBgCamIndex(CollisionContext* colCtx, WaterBox* waterBox) {
     u32 prop = waterBox->properties >> 0;
 
     return prop & 0xFF;
 }
 
 /**
- * WaterBox get CamData camera setting
+ * WaterBox get BgCam setting
  */
-u16 WaterBox_GetCameraSetting(CollisionContext* colCtx, WaterBox* waterBox, s32 bgId) {
+u16 WaterBox_GetBgCamSetting(CollisionContext* colCtx, WaterBox* waterBox, s32 bgId) {
     s32 pad[2];
-    u16 result = 0;
+    u16 camSetting = CAM_SET_NONE;
     CollisionHeader* colHeader;
-    CamData* camData;
-    s32 camId;
+    BgCamInfo* bgCamList;
+    s32 bgCamIndex;
 
     colHeader = BgCheck_GetCollisionHeader(colCtx, bgId);
     if (colHeader == NULL) {
-        return result;
-    }
-    camId = WaterBox_GetCamDataIndex(colCtx, waterBox);
-    camData = colHeader->cameraDataList;
-
-    if (camData == NULL) {
-        return result;
+        return camSetting;
     }
 
-    result = camData[camId].setting;
-    return result;
+    bgCamIndex = WaterBox_GetBgCamIndex(colCtx, waterBox);
+    bgCamList = colHeader->bgCamList;
+
+    if (bgCamList == NULL) {
+        return camSetting;
+    }
+
+    camSetting = bgCamList[bgCamIndex].setting;
+
+    return camSetting;
 }
 
-void func_800CA6B8(CollisionContext* colCtx, WaterBox* waterBox) {
-    WaterBox_GetCameraSetting(colCtx, waterBox, BGCHECK_SCENE);
+/**
+ * WaterBox get scene BgCam setting
+ */
+void WaterBox_GetSceneBgCamSetting(CollisionContext* colCtx, WaterBox* waterBox) {
+    WaterBox_GetBgCamSetting(colCtx, waterBox, BGCHECK_SCENE);
 }
 
 /**

src/code/z_camera.c

@@ -38,7 +38,22 @@
 
 #pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CB854.s")
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CB880.s")
+s32 Camera_IsSwimming(Camera* camera) {
+    Actor* focalActor = camera->focalActor;
+
+    if (focalActor == &GET_PLAYER(camera->play)->actor) {
+        if (((Player*)focalActor)->stateFlags3 & PLAYER_STATE3_8000) {
+            // Swimming as Zora
+            return 999;
+        } else {
+            // Swimming as Human or Fierce Deity
+            return ((Player*)focalActor)->stateFlags1 & PLAYER_STATE1_8000000;
+        }
+    } else {
+        // Camera not focused on player
+        return 0;
+    }
+}
 
 #pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CB8C8.s")
 
@@ -84,13 +99,78 @@
 
 #pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CC5C8.s")
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CC740.s")
+#define CAM_DATA_IS_BG (1 << 12) // if not set, then cam data is for actor cutscenes
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CC7A8.s")
+/**
+ * Returns the CameraSettingType of the camera from either the bgCam or the actorCsCam at index `camDataId`
+ */
+s16 Camera_GetBgCamOrActorCsCamSetting(Camera* camera, u32 camDataId) {
+    if (camDataId & CAM_DATA_IS_BG) {
+        return BgCheck_GetBgCamSettingImpl(&camera->play->colCtx, camDataId & ~CAM_DATA_IS_BG, BGCHECK_SCENE);
+    } else {
+        return Play_GetActorCsCamSetting(camera->play, camDataId);
+    }
+}
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CC804.s")
+/**
+ * Returns either the bgCam data or the actorCsCam data at index `camDataId`
+ */
+Vec3s* Camera_GetBgCamOrActorCsCamFuncData(Camera* camera, u32 camDataId) {
+    if (camDataId & CAM_DATA_IS_BG) {
+        return BgCheck_GetBgCamFuncDataImpl(&camera->play->colCtx, camDataId & ~CAM_DATA_IS_BG, BGCHECK_SCENE);
+    } else {
+        return Play_GetActorCsCamFuncData(camera->play, camDataId);
+    }
+}
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CC874.s")
+/**
+ * Gets the bgCam index for the poly `poly`, returns -1 if
+ * there is no camera data for that poly.
+ */
+s32 Camera_GetBgCamIndex(Camera* camera, s32* bgId, CollisionPoly* poly) {
+    s32 bgCamIndex = SurfaceType_GetBgCamIndex(&camera->play->colCtx, poly, *bgId);
+    s32 ret;
+
+    if (BgCheck_GetBgCamSettingImpl(&camera->play->colCtx, bgCamIndex, *bgId) == CAM_SET_NONE) {
+        ret = -1;
+    } else {
+        ret = bgCamIndex;
+    }
+
+    return ret;
+}
+
+/**
+ * Gets the Camera setting for the water box the player is in.
+ * Returns -1 if the player is not in a water box, or does not have a swimming state.
+ * Returns -2 if there is no bgCam index for the water box.
+ * Returns the camera setting otherwise.
+ */
+s32 Camera_GetWaterBoxBgCamSetting(Camera* camera, f32* waterY) {
+    PosRot playerPosShape;
+    WaterBox* waterBox;
+    s32 camSetting;
+    s32 bgId;
+
+    Actor_GetWorldPosShapeRot(&playerPosShape, camera->focalActor);
+    *waterY = playerPosShape.pos.y;
+
+    if (!WaterBox_GetSurfaceImpl(camera->play, &camera->play->colCtx, playerPosShape.pos.x, playerPosShape.pos.z,
+                                 waterY, &waterBox, &bgId)) {
+        // player's position is not in a waterbox
+        *waterY = playerPosShape.pos.y;
+        return -1;
+    }
+
+    if (!Camera_IsSwimming(camera)) {
+        return -1;
+    }
+
+    camSetting = WaterBox_GetBgCamSetting(&camera->play->colCtx, waterBox, bgId);
+
+    // -2: no bgCam index
+    return (camSetting == CAM_SET_NONE) ? -2 : camSetting;
+}
 
 #pragma GLOBAL_ASM("asm/non_matchings/code/z_camera/func_800CC938.s")
 

src/code/z_play.c

@@ -108,9 +108,17 @@ s32 Play_InCsMode(PlayState* this) {
 
 #pragma GLOBAL_ASM("asm/non_matchings/code/z_play/func_80169BF8.s")
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_play/Play_GetCsCamDataSetting.s")
+u16 Play_GetActorCsCamSetting(PlayState* this, s32 csCamDataIndex) {
+    ActorCsCamInfo* actorCsCamList = &this->actorCsCamList[csCamDataIndex];
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_play/Play_GetCsCamDataVec3s.s")
+    return actorCsCamList->setting;
+}
+
+Vec3s* Play_GetActorCsCamFuncData(PlayState* this, s32 csCamDataIndex) {
+    ActorCsCamInfo* actorCsCamList = &this->actorCsCamList[csCamDataIndex];
+
+    return Lib_SegmentedToVirtual(actorCsCamList->actorCsCamFuncData);
+}
 
 /**
  * Converts the number of a scene to its "original" equivalent, the default version of the area which the player first

src/code/z_scene.c

@@ -173,9 +173,9 @@ void Scene_HeaderCmdActorList(PlayState* play, SceneCmd* cmd) {
     play->actorCtx.unkC = 0;
 }
 
-// SceneTableEntry Header Command 0x02: List of cameras for actor cutscenes
+// SceneTableEntry Header Command 0x02: List of camera data for actor cutscenes
 void Scene_HeaderCmdActorCutsceneCamList(PlayState* play, SceneCmd* cmd) {
-    play->csCamData = Lib_SegmentedToVirtual(cmd->csCameraList.segment);
+    play->actorCsCamList = Lib_SegmentedToVirtual(cmd->actorCsCamList.segment);
 }
 
 // SceneTableEntry Header Command 0x03: Collision Header
@@ -192,8 +192,8 @@ void Scene_HeaderCmdColHeader(PlayState* play, SceneCmd* cmd) {
         colHeader->surfaceTypeList = Lib_SegmentedToVirtual(colHeader->surfaceTypeList);
     }
 
-    if (colHeader->cameraDataList != NULL) {
-        colHeader->cameraDataList = Lib_SegmentedToVirtual(colHeader->cameraDataList);
+    if (colHeader->bgCamList != NULL) {
+        colHeader->bgCamList = Lib_SegmentedToVirtual(colHeader->bgCamList);
     }
 
     if (colHeader->waterBoxes != NULL) {