z_camera with Partial Docs (3 Non-Equivalent) (#601)

* more boot files

* Add VT macros and script

* finish already existing boot files

* most of  libultra

* fix 64bits libultra files

* Use C files for libultra, wrap some functions in NON_MATCHING

* Remove duplicate of OS_CLOCK_RATE from fault.c

* C files for fbdemos

* delete dumb files

* bootstrap C files, still need to add them to the spec

* update fixbaserom

* boot OK?

* I forgot to commit the spec

* C for gamestates

* C for kaleido

* Change all includes to ""

* copy actor sizes script from oot

* I forgot to delete those files

* Basic C files for effects

* Add effects initvars names

* Remove mislabelled boot functions from header/txt

* Begin porting bootstrap_fx, some sizes

* Fix <>

* Fix enum

* Fix diff.py

* fix libultra stuff

* update regconvert

* update setup warnings

* add some missing ;

* Fix some makefile stuff and other fixes on some non_matching functions

* add executable flag in extract_baserom and fixbaserom

* fix relative path

* copy assist from oot

* fix map path

* another assist path fix

* Delete C files for handwritten files

* add code_801A51F0 to spec

* add gfxbuffers to spec

* Move rodata to top of each file when possible

* UNK_TYPEs for func_801A51F0

* Remove kaleido rodata from spec

* Update spec and undefined_syms for recent merge

* GCC warnings and fix errors in nonmatchings,

* round percentage numbers

* progress script: format changes

* progress: error on non-existing files

* fix warning in z_scene_table

* Match 2 nonmatchings in z_actor

* Warnings in lightswitch and invadepoh

* Fix warning in z_actor_dlftbls

* I though I fixed this one

* whoops

* Comment out CC_CHECK

* Removed redundant ultra64.h includes

* Update asm_processor, sorted boot_O1 into other folders, completed the fbdemo bootstrap, cleaned up undefined_syms

* Completed gamestates bootstrap

* Split kaleido_scope

* Remove section.h and segment.h, move keep object externs to a common location in variables.h

* Completed effects bootstrap

* Segmented address externs for effects, fbdemos, gamestates and kaleido

* Move actor data externs out of the if 0

* Segmented address externs for actors

* Prepare actionfunc detection

* fix script, how did it even work before

* Fix actionfunc script again, re-introduce some more intermediate prints to the disassembler

* Automated actionFunc detection in actors

* Segmented addresses from player .text

* rm old segment addrs script and fix build

* Move sizes folder to tools

* Make build.py executable

* New Jenkinsfile Prayge

* Remove numpy dependencies

* Add warnings_disasm_current.txt

* my bad

* Update spec and undefined_syms

* Add z_eff_ss_hahen to pametfrog

* git subrepo pull (merge) --force tools/z64compress

subrepo:
  subdir:   "tools/z64compress"
  merged:   "163ca2af"
upstream:
  origin:   "https://github.com/z64me/z64compress.git"
  branch:   "main"
  commit:   "163ca2af"
git-subrepo:
  version:  "0.4.3"
  origin:   "https://github.com/ingydotnet/git-subrepo"
  commit:   "2f68596"

* Make z64compress print to stdout

* sneeky commit to update warnings tooling

* test

* Another test

* Mark fixing overlay reloc generating as a TODO

* Update warnings stuff

* Communicate the return code from running z64compress back to the Makefile through the wrapper

* Run formatter, remove extra commented copy of function

* Re-fix some includes

* Convert atan to hex to conform to decided style

* Clean up most matching with rodata and most warnings

* Match Parallel1, minor improvement in Jump and KeepOn

* Begin Documentation

* More docs, fixed warnings

* cleanup

* Continuing with docs

* Small progress

* Fix BSS, All but 1 matching functions freed, continue docs

* Fix merge

* Many function names

* More Names

* Change name

* Docs

* Begin camera_data docs

* small progress

* Minor change

* Improve docs on functions

* Player to TrackActor, progress on camera_data

* Add Cam_Data Macro and fix warnings

* Progress on Camera_Data docs

* Document CsCamData

* Cleanup

* Minor clean up in Battle NON_MATCHING

* Small fixes

* Fix bss, OK

* typo

* revert some z64 macros and format

* OK

* minor settings docs

* Many flags, names, and other documentation

* Name many camera_data variables

* A few more small changes

* Refactoring Camera Action Function Structs WIP

* Finish Struct reworking

* Some door docs

* Add my findings of Camera Settings as comments

* More camera data names and comments cleanup

* A few names

* Slow progress on camera_data

* More camera_data progress, slow and steady

* Many renaming

* wip

* camera_data WIP

* The grind continues

* More data wip

* All the macros are in!

* Format and cleanup

* more docs

* format

* Breakup camera into pieces

* format

* PR Feedback round 1

* revert macro

* Fix header

* Document Play Camera and Screen pos

* cleanup

* revert camera split

* Start copying docs from OoT

* remaining CAM_INTERFACE_FLAGS

* roData and rwData

* Change paramData

* Flags

* More docs

* More Cleanup

* cleanup

* more

* More docs

* Standardize subcams

* macro

* Player_UpdateCamAndSeqModes

* cleanup from PR

* format

* sync with bgCam and actorsCsCam PR

* sync to z_play cam PR

* docs progress

* revert player changes

* helper function cleanup

* match Jump3, thanks petrie & synray

* camera bg docs

* brackets

* cam math docs

* more cam bg docs

* rename flags

* misc docs

* more cleanup

* some cam docs

* some PR

* hud visibility

* fix macros, sync with PR

* sync with PR

* sync with PR

* helper cleanup

* cleanup

* PR Suggestions

* more PR

* fix merge master

* PR review

* add comment

* more quake cleanup

* pr suggestions

---------

Co-authored-by: angie <angheloalf95@gmail.com>
Co-authored-by: Elliptic Ellipsis <elliptic.ellipsis@gmail.com>
Co-authored-by: Tharo <17233964+Thar0@users.noreply.github.com>

include/functions.h

@@ -133,7 +133,7 @@ void SystemArena_FreeNullCheck(void* ptr);
 void SystemArena_RunInits(void);
 void SystemArena_Init(void* start, size_t size);
 s32 func_80086620(OSMesgQueue* param_1, PadMgr* param_2, OSContStatus* param_3);
-// void func_80086760(void);
+f32 func_80086760(f32 x);
 // void func_80086794(void);
 // void func_800867B4(void);
 // void func_800867D4(void);
@@ -797,47 +797,45 @@ s32 DynaPolyActor_IsSwitchPressed(DynaPolyActor* dynaActor);
 s32 DynaPolyActor_IsHeavySwitchPressed(DynaPolyActor* dynaActor);
 s32 DynaPolyActor_ValidateMove(PlayState* play, DynaPolyActor* dynaActor, s16 startRadius, s16 endRadius, s16 startHeight);
 
-Camera* Camera_Alloc(View* view, CollisionContext* bg, PlayState* play);
-void Camera_Free(Camera* camera);
-void Camera_Init(Camera* camera, View* view, CollisionContext* bg, PlayState* play);
-// void func_800DDFE0(void);
-void Camera_InitPlayerSettings(Camera* camera, Player* player);
+Camera* Camera_Create(View* view, CollisionContext* colCtx, PlayState* play);
+void Camera_Destroy(Camera* camera);
+void Camera_Init(Camera* camera, View* view, CollisionContext* colCtx, PlayState* play);
+void func_800DDFE0(Camera* camera);
+void Camera_InitFocalActorSettings(Camera* camera, Actor* focalActor);
 s32 Camera_ChangeStatus(Camera* camera, s16 status);
-// void func_800DE324(void);
-// void func_800DE62C(void);
-// void func_800DE840(void);
-// void func_800DE890(void);
-// UNK_TYPE4 func_800DE954(Camera* camera);
-Vec3s* Camera_Update(Vec3s* param_1, Camera* camera);
-// void func_800DF498(void);
-u32 Camera_SetMode(Camera* camera, s16 mode, s8 param_3);
+s32 Camera_UpdateWater(Camera* camera);
+void Camera_EarthquakeDay3(Camera* camera);
+s32 Camera_UpdateHotRoom(Camera* camera);
+s32 Camera_SetSwordDistortion(Camera* camera);
+s32 Camera_RequestGiantsMaskSetting(Camera* camera);
+Vec3s* Camera_Update(Vec3s* inputDir, Camera* camera);
+s32 func_800DF498(Camera* camera);
+s32 Camera_ChangeModeFlags(Camera* camera, s16 mode, u8 forceChange);
 s32 Camera_ChangeMode(Camera* camera, s16 mode);
-s32 func_800DF86C(Camera* camera, s16 arg1);
-// void func_800DF8EC(void);
+s32 Camera_CheckValidMode(Camera* camera, s16 mode);
+s16 Camera_ChangeSettingFlags(Camera* camera, s16 setting, s16 flags);
 s32 Camera_ChangeSetting(Camera* camera, s16 setting);
-s32 Camera_ChangeDataIdx(Camera* camera, s32 camDataIdx);
-// void func_800DFC1C(void);
-// void func_800DFC40(void);
-s32 Camera_GetInputDirYaw(Camera* camera);
-void Camera_GetCamDir(Vec3s* dst, Camera* camera);
+s32 Camera_ChangeActorCsCamIndex(Camera* camera, s32 bgCamIndex);
+Vec3s* Camera_GetInputDir(Vec3s* dst, Camera* camera);
+s16 Camera_GetInputDirPitch(Camera* camera);
+s16 Camera_GetInputDirYaw(Camera* camera);
+Vec3s* Camera_GetCamDir(Vec3s* dst, Camera* camera);
 s16 Camera_GetCamDirPitch(Camera* camera);
 s16 Camera_GetCamDirYaw(Camera* camera);
-void Camera_AddQuake(Camera* camera, s32 arg1, s16 y, s32 countdown);
+s32 Camera_AddQuake(Camera* camera, s32 arg1, s16 y, s32 countdown);
 s32 Camera_SetViewParam(Camera* camera, s32 viewFlag, void* param);
-// UNK_TYPE4 func_800DFEF0(s32 param_1, u16 param_2);
-void func_800DFF18(Camera* camera, s32 arg1);
-// UNK_TYPE4 func_800DFF34(s32 param_1);
-// UNK_TYPE4 func_800DFF44(void);
-s16 Camera_SetFlags(Camera* iParm1, s16 flags);
-s16 Camera_ClearFlags(Camera* camera, s16 flags);
+s32 Camera_UnsetViewFlag(Camera* camera, s16 viewFlag);
+s32 Camera_OverwriteStateFlags(Camera* camera, s16 stateFlags);
+s16 Camera_SetStateFlag(Camera* camera, s16 flags);
+s16 Camera_UnsetStateFlag(Camera* camera, s16 flags);
 s32 Camera_ChangeDoorCam(Camera* camera, Actor* doorActor, s16 bgCamIndex, f32 arg3, s16 timer1, s16 timer2, s16 timer3);
-s32 Camera_Copy(Camera* dstCamera, Camera* srcCamera);
-// UNK_TYPE4 func_800E01AC(void);
+s32 Camera_Copy(Camera* dstCam, Camera* srcCam);
+s32 Camera_IsDbgCamEnabled(void);
 Vec3f* Camera_GetQuakeOffset(Vec3f* quakeOffset, Camera* camera);
-// void func_800E01DC(s32 param_1, u32 param_2, UNK_TYPE4 param_3, UNK_TYPE4 param_4, UNK_TYPE2 param_5, UNK_TYPE2 param_6);
-// UNK_TYPE4 func_800E0228(void);
-void func_800E0238(Camera* camera);
-void Camera_SetToTrackActor(Camera* camera, Actor* actor);
+void Camera_SetCameraData(Camera* camera, s16 setDataFlags, void* data0, void* data1, s16 data2, s16 data3);
+s32 Camera_GetNegOne(void);
+s16 func_800E0238(Camera* camera);
+void Camera_SetFocalActor(Camera* camera, Actor* actor);
 void Camera_SetTargetActor(Camera* camera, Actor* actor);
 f32 Camera_GetWaterYPos(Camera* camera);
 void func_800E0348(Camera* camera);
@@ -2191,8 +2189,8 @@ f32 randPlusMinusPoint5Scaled(f32 scale);
 f32 Math3D_Normalize(Vec3f* vec);
 s32 Math3D_PlaneVsLineSegClosestPoint(f32 planeAA, f32 planeAB, f32 planeAC, f32 planeADist, f32 planeBA, f32 planeBB, f32 planeBC, f32 planeBDist, Vec3f* linePointA, Vec3f* linePointB, Vec3f* closestPoint);
 s32 func_80179798(Vec3f* param_1, Vec3f* param_2, Vec3f* param_3, Vec3f* param_4, Vec3f* param_5, Vec3f* param_6);
-// void func_80179A44(void);
-void func_80179B34(float fParm1, f32 fParm2, f32 fParm5, f32 fParm6, f32 param_5, f32 param_6, f32 param_7, float* param_8, float* param_9);
+void func_80179A44(Vec3f* arg0, PosRot* arg1, Vec3f* arg2);
+void func_80179B34(f32 arg0, f32 arg1, f32 arg2, f32 arg3, f32 arg4, f32 arg5, f32 arg6, f32* arg7, f32* arg8);
 // UNK_TYPE4 func_80179B94(f32 fParm1, f32 fParm2, f32 fParm5, f32 param_4, f32 param_5, f32 param_6, f32 param_7, f32 param_8, Vec3f* param_9);
 // void func_80179D74(UNK_TYPE1 param_1, UNK_TYPE1 param_2, UNK_TYPE1 param_3, UNK_TYPE1 param_4, UNK_TYPE4 param_5, UNK_TYPE4 param_6, UNK_TYPE4 param_7, UNK_TYPE4 param_8, UNK_TYPE4 param_9, UNK_TYPE4 param_10);
 void Math3D_ScaleAndAdd(Vec3f* a, Vec3f* b, f32 scale, Vec3f* dst);

include/variables.h

@@ -384,23 +384,6 @@ extern BgCheckSceneSubdivisionEntry sSceneSubdivisionList[];
 extern BgSpecialSceneMaxObjects sCustomDynapolyMem[];
 // extern UNK_TYPE1 D_801B4708;
 
-// extern UNK_TYPE4 D_801B9E0C;
-// extern UNK_TYPE4 D_801B9E10;
-// extern UNK_TYPE4 D_801B9E14;
-// extern UNK_TYPE2 D_801B9E18;
-// extern UNK_TYPE2 D_801B9E34;
-// extern UNK_TYPE4 D_801B9E50;
-// extern UNK_TYPE4 D_801B9E54;
-// extern UNK_TYPE4 D_801B9E58;
-// extern UNK_TYPE4 D_801B9E5C;
-// extern UNK_TYPE4 D_801B9E60;
-// extern UNK_TYPE1 D_801B9E64;
-// extern UNK_TYPE1 D_801B9E84;
-// extern UNK_TYPE4 D_801B9EB4;
-// extern UNK_TYPE4 D_801B9ED4;
-// extern UNK_TYPE4 sEarthquakeFreq;
-// extern UNK_TYPE2 sEarthquakeTimer;
-extern UNK_TYPE4 D_801B9F10;
 extern DamageTable sDamageTablePresets[23];
 extern f32 damageMultipliers[16];
 extern Collider defaultCollider;
@@ -2240,7 +2223,7 @@ extern f32 D_801ED8D0;
 // extern UNK_TYPE1 D_801ED8D8;
 // extern UNK_TYPE1 D_801ED8DC;
 extern Mtx D_801ED8E0;
-// extern UNK_TYPE1 D_801ED920;
+extern Actor* D_801ED920;
 extern FaultClient sActorOverlayTableFaultClient;
 extern FaultAddrConvClient sActorOverlayTableFaultAddrConvClient;
 extern char D_801ED950[80];
@@ -2256,20 +2239,6 @@ extern Vec3f D_801EDB70[3];
 extern Plane D_801EDB98;
 extern Sphere16 D_801EDBA8;
 extern TriNorm D_801EDBB0;
-// extern UNK_TYPE1 D_801EDBD4;
-// extern UNK_TYPE1 D_801EDBD8;
-// extern UNK_TYPE1 D_801EDBDC;
-// extern UNK_TYPE1 D_801EDBE0;
-
-// extern s16 D_801EDBF0;
-// extern f32 D_801EDBF4;
-// extern f32 D_801EDBF8;
-// extern CameraCollision D_801EDC00;
-// extern PlayState* sCamPlayState;
-// extern SwingAnimation D_801EDC30[4];
-// extern Vec3f D_801EDDD0;
-// extern Vec3f D_801EDDE0;
-// extern Vec3f D_801EDDF0;
 
 extern Vec3f D_801EDE00;
 extern Vec3f D_801EDE10;

include/z64bgcheck.h

@@ -255,7 +255,7 @@ typedef struct {
     /* 0x14 */ u16 numPolygons;
     /* 0x18 */ CollisionPoly* polyList;
     /* 0x1C */ SurfaceType* surfaceTypeList;
-    /* 0x20 */ CamData* bgCamList;
+    /* 0x20 */ BgCamInfo* bgCamList;
     /* 0x24 */ u16 numWaterBoxes;
     /* 0x28 */ WaterBox* waterBoxes;
 } CollisionHeader; // size = 0x2C

include/z64camera.h

@@ -90,18 +90,18 @@
 #define CAM_BEHAVIOR_SETTING_2 (1 << 4)
 // Mode (0x2, 0x20)
 #define CAM_BEHAVIOR_MODE_1 (1 << 1)
-#define CAM_BEHAVIOR_MODE_2 (1 << 5)
+#define CAM_BEHAVIOR_MODE_VALID (1 << 5)
 // bgCam (0x4, 0x40)
 #define CAM_BEHAVIOR_BGCAM_1 (1 << 2)
 #define CAM_BEHAVIOR_BGCAM_2 (1 << 6)
 
 // Camera stateFlags. Variety of generic flags
 #define CAM_STATE_0 (1 << 0) // Must be set for the camera from changing settings based on the bg surface
-#define CAM_STATE_1 (1 << 1)
+#define CAM_STATE_CHECK_WATER (1 << 1)
 #define CAM_STATE_2 (1 << 2)
 #define CAM_STATE_3 (1 << 3)
 #define CAM_STATE_4 (1 << 4)
-#define CAM_STATE_5 (1 << 5)
+#define CAM_STATE_DISABLE_MODE_CHANGE (1 << 5)
 #define CAM_STATE_6 (1 << 6)
 #define CAM_STATE_7 (1 << 7)
 #define CAM_STATE_UNDERWATER (1 << 8)
@@ -110,7 +110,7 @@
 #define CAM_STATE_11 (1 << 11)
 #define CAM_STATE_12 (1 << 12)
 #define CAM_STATE_13 (1 << 13)
-#define CAM_STATE_14 (1 << 14)
+#define CAM_STATE_INITIALIZED (1 << 14)
 #define CAM_STATE_15 ((s16)(1 << 15))
 
 // Camera viewFlags. Set params related to view
@@ -340,13 +340,13 @@ typedef enum {
 } CameraFuncType;
 
 typedef enum {
-    /* 0x00 */ CAM_DATA_00,
+    /* 0x00 */ CAM_DATA_Y_OFFSET,
     /* 0x01 */ CAM_DATA_01,
     /* 0x02 */ CAM_DATA_02,
-    /* 0x03 */ CAM_DATA_03,
+    /* 0x03 */ CAM_DATA_PITCH_TARGET,
     /* 0x04 */ CAM_DATA_04,
     /* 0x05 */ CAM_DATA_05,
-    /* 0x06 */ CAM_DATA_06,
+    /* 0x06 */ CAM_DATA_YAW_DIFF_RANGE,
     /* 0x07 */ CAM_DATA_FOV,
     /* 0x08 */ CAM_DATA_08,
     /* 0x09 */ CAM_DATA_INTERFACE_FLAGS,
@@ -405,13 +405,13 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_NORM1(yOffset, data01, data02, pitchTarget, eyeStepScale, posStepScale, yawDiffRange, fov, data08, interfaceFlags) \
-    { yOffset,      CAM_DATA_00 }, \
+    { yOffset,      CAM_DATA_Y_OFFSET }, \
     { data01,       CAM_DATA_01 }, \
     { data02,       CAM_DATA_02 }, \
-    { pitchTarget,  CAM_DATA_03 }, \
+    { pitchTarget,  CAM_DATA_PITCH_TARGET }, \
     { eyeStepScale, CAM_DATA_04 }, \
     { posStepScale, CAM_DATA_05 }, \
-    { yawDiffRange, CAM_DATA_06 }, \
+    { yawDiffRange, CAM_DATA_YAW_DIFF_RANGE }, \
     { fov,          CAM_DATA_FOV }, \
     { data08,       CAM_DATA_08 }, \
     { interfaceFlags, CAM_DATA_INTERFACE_FLAGS }
@@ -462,10 +462,10 @@ typedef struct {
 // Unused Camera RemoteBomb Setting
 
 #define CAM_FUNCDATA_NORM2(yOffset, data01, data02, pitchTarget, data04, fov, data08, interfaceFlags) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data01,      CAM_DATA_01 }, \
     { data02,      CAM_DATA_02 }, \
-    { pitchTarget, CAM_DATA_03 }, \
+    { pitchTarget, CAM_DATA_PITCH_TARGET }, \
     { data04,      CAM_DATA_04 }, \
     { fov,         CAM_DATA_FOV }, \
     { data08,      CAM_DATA_08 }, \
@@ -480,10 +480,10 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_NORM3(yOffset, data01, data02, pitchTarget, eyeStepScale, posStepScale, fov, data08, interfaceFlags) \
-    { yOffset,      CAM_DATA_00 }, \
+    { yOffset,      CAM_DATA_Y_OFFSET }, \
     { data01,       CAM_DATA_01 }, \
     { data02,       CAM_DATA_02 }, \
-    { pitchTarget,  CAM_DATA_03 }, \
+    { pitchTarget,  CAM_DATA_PITCH_TARGET }, \
     { eyeStepScale, CAM_DATA_04 }, \
     { posStepScale, CAM_DATA_05 }, \
     { fov,          CAM_DATA_FOV }, \
@@ -530,12 +530,12 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_NORM0(yOffset, data01, data02, data21, data04, yawDiffRange, fov, data08, interfaceFlags) \
-    { yOffset,      CAM_DATA_00 }, \
+    { yOffset,      CAM_DATA_Y_OFFSET }, \
     { data01,       CAM_DATA_01 }, \
     { data02,       CAM_DATA_02 }, \
     { data21,       CAM_DATA_21 }, \
     { data04,       CAM_DATA_04 }, \
-    { yawDiffRange, CAM_DATA_06 }, \
+    { yawDiffRange, CAM_DATA_YAW_DIFF_RANGE }, \
     { fov,          CAM_DATA_FOV }, \
     { data08,       CAM_DATA_08 }, \
     { interfaceFlags, CAM_DATA_INTERFACE_FLAGS }
@@ -581,10 +581,10 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_PARA1(yOffset, data01, data02, pitchTarget, data10, data04, data05, fov, data08, interfaceFlags, data11, data12) \
-    { yOffset,      CAM_DATA_00 }, \
+    { yOffset,      CAM_DATA_Y_OFFSET }, \
     { data01,       CAM_DATA_01 }, \
     { data02,       CAM_DATA_02 }, \
-    { pitchTarget,  CAM_DATA_03 }, \
+    { pitchTarget,  CAM_DATA_PITCH_TARGET }, \
     { data10,       CAM_DATA_10 }, \
     { data04,       CAM_DATA_04 }, \
     { data05,       CAM_DATA_05 }, \
@@ -596,10 +596,10 @@ typedef struct {
 
 // Same as above but with extra unused entry
 #define CAM_FUNCDATA_PARA1_ALT(yOffset, data01, data02, pitchTarget, data10, data04, data05, fov, data08, interfaceFlags, data11, data12, data18) \
-    { yOffset,      CAM_DATA_00 }, \
+    { yOffset,      CAM_DATA_Y_OFFSET }, \
     { data01,       CAM_DATA_01 }, \
     { data02,       CAM_DATA_02 }, \
-    { pitchTarget,  CAM_DATA_03 }, \
+    { pitchTarget,  CAM_DATA_PITCH_TARGET }, \
     { data10,       CAM_DATA_10 }, \
     { data04,       CAM_DATA_04 }, \
     { data05,       CAM_DATA_05 }, \
@@ -662,10 +662,10 @@ typedef struct {
 // Unused Camera Maze Setting
 
 #define CAM_FUNCDATA_PARA2(yOffset, data02, data01, pitchTarget, data04, fov, data08, interfaceFlags) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data02,      CAM_DATA_02 }, \
     { data01,      CAM_DATA_01 }, \
-    { pitchTarget, CAM_DATA_03 }, \
+    { pitchTarget, CAM_DATA_PITCH_TARGET }, \
     { data04,      CAM_DATA_04 }, \
     { fov,         CAM_DATA_FOV }, \
     { data08,      CAM_DATA_08 }, \
@@ -680,7 +680,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_JUMP2(yOffset, data01, data02, data20, data04, data05, fov, data08, interfaceFlags) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data01,      CAM_DATA_01 }, \
     { data02,      CAM_DATA_02 }, \
     { data20,      CAM_DATA_20 }, \
@@ -729,13 +729,13 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_JUMP3(yOffset, data01, data02, pitchTarget, data04, data05, yawDiffRange, fov, data08, interfaceFlags) \
-    { yOffset,      CAM_DATA_00 }, \
+    { yOffset,      CAM_DATA_Y_OFFSET }, \
     { data01,       CAM_DATA_01 }, \
     { data02,       CAM_DATA_02 }, \
-    { pitchTarget,  CAM_DATA_03 }, \
+    { pitchTarget,  CAM_DATA_PITCH_TARGET }, \
     { data04,       CAM_DATA_04 }, \
     { data05,       CAM_DATA_05 }, \
-    { yawDiffRange, CAM_DATA_06 }, \
+    { yawDiffRange, CAM_DATA_YAW_DIFF_RANGE }, \
     { fov,          CAM_DATA_FOV }, \
     { data08,       CAM_DATA_08 }, \
     { interfaceFlags, CAM_DATA_INTERFACE_FLAGS }
@@ -785,7 +785,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_BATT1(yOffset, data01, data02, data13, data14, data15, data16, data17, fov, data08, interfaceFlags, data11, data18) \
-    { yOffset, CAM_DATA_00 }, \
+    { yOffset, CAM_DATA_Y_OFFSET }, \
     { data01,  CAM_DATA_01 }, \
     { data02,  CAM_DATA_02 }, \
     { data13,  CAM_DATA_13 }, \
@@ -845,7 +845,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_KEEP1(yOffset, data01, data02, data13, data14, data15, data16, data17, fov, data08, interfaceFlags, data11) \
-    { yOffset, CAM_DATA_00 }, \
+    { yOffset, CAM_DATA_Y_OFFSET }, \
     { data01,  CAM_DATA_01 }, \
     { data02,  CAM_DATA_02 }, \
     { data13,  CAM_DATA_13 }, \
@@ -902,7 +902,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_KEEP3(yOffset, data01, data02, data13, data14, data15, data16, data17, fov, data08, timer, interfaceFlags, data18) \
-    { yOffset, CAM_DATA_00 }, \
+    { yOffset, CAM_DATA_Y_OFFSET }, \
     { data01,  CAM_DATA_01 }, \
     { data02,  CAM_DATA_02 }, \
     { data13,  CAM_DATA_13 }, \
@@ -957,9 +957,9 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_KEEP4(yOffset, data01, pitchTarget, data10, data18, fov, interfaceFlags, data04, timer) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data01,      CAM_DATA_01 }, \
-    { pitchTarget, CAM_DATA_03 }, \
+    { pitchTarget, CAM_DATA_PITCH_TARGET }, \
     { data10,      CAM_DATA_10 }, \
     { data18,      CAM_DATA_18 }, \
     { fov,         CAM_DATA_FOV }, \
@@ -1008,7 +1008,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_FIXD1(yOffset, data04, fov, interfaceFlags) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data04,      CAM_DATA_04 }, \
     { fov,         CAM_DATA_FOV }, \
     { interfaceFlags, CAM_DATA_INTERFACE_FLAGS }
@@ -1040,7 +1040,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_FIXD2(yOffset, data01, data02, data04, data05, fov, interfaceFlags) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data01,      CAM_DATA_01 }, \
     { data02,      CAM_DATA_02 }, \
     { data04,      CAM_DATA_04 }, \
@@ -1097,7 +1097,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_SUBJ1(yOffset, data01, data02, data04, data19, data17, data18, fov, interfaceFlags) \
-    { yOffset, CAM_DATA_00 }, \
+    { yOffset, CAM_DATA_Y_OFFSET }, \
     { data01,  CAM_DATA_01 }, \
     { data02,  CAM_DATA_02 }, \
     { data04,  CAM_DATA_04 }, \
@@ -1140,7 +1140,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_UNIQ2(yOffset, data01, fov, interfaceFlags) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data01,      CAM_DATA_01 }, \
     { fov,         CAM_DATA_FOV }, \
     { interfaceFlags, CAM_DATA_INTERFACE_FLAGS }
@@ -1175,7 +1175,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_UNIQ0(yOffset, data04, interfaceFlags) \
-    { yOffset,     CAM_DATA_00 }, \
+    { yOffset,     CAM_DATA_Y_OFFSET }, \
     { data04,      CAM_DATA_04 }, \
     { interfaceFlags, CAM_DATA_INTERFACE_FLAGS }
 
@@ -1387,10 +1387,10 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_SPEC5(yOffset, eyeDist, minDistForRot, fov, atMaxLERPScale, timerInit, pitch, interfaceFlags) \
-    { yOffset,        CAM_DATA_00 }, \
+    { yOffset,        CAM_DATA_Y_OFFSET }, \
     { eyeDist,        CAM_DATA_01 }, \
     { minDistForRot,  CAM_DATA_02 }, \
-    { fov,            CAM_DATA_03 }, \
+    { fov,            CAM_DATA_PITCH_TARGET }, \
     { atMaxLERPScale, CAM_DATA_FOV }, \
     { timerInit,      CAM_DATA_08 }, \
     { pitch,          CAM_DATA_12 }, \
@@ -1446,7 +1446,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_SPEC8(yOffset, eyeStepScale, posStepScale, fov, spiralDoorCsLength, interfaceFlags) \
-    { yOffset,            CAM_DATA_00 }, \
+    { yOffset,            CAM_DATA_Y_OFFSET }, \
     { eyeStepScale,       CAM_DATA_04 }, \
     { posStepScale,       CAM_DATA_05 }, \
     { fov,                CAM_DATA_FOV }, \
@@ -1483,7 +1483,7 @@ typedef struct {
  */
 
 #define CAM_FUNCDATA_SPEC9(yOffset, fov, interfaceFlags) \
-    { yOffset, CAM_DATA_00 }, \
+    { yOffset, CAM_DATA_Y_OFFSET }, \
     { fov,     CAM_DATA_FOV }, \
     { interfaceFlags, CAM_DATA_INTERFACE_FLAGS }
 
@@ -1565,11 +1565,11 @@ typedef struct Camera {
     /* 0x0D8 */ f32 xzSpeed;
     /* 0x0DC */ f32 dist;
     /* 0x0E0 */ f32 speedRatio;
-    /* 0x0E4 */ Vec3f atActorOffset;
-    /* 0x0F0 */ Vec3f focalActorOffset;
+    /* 0x0E4 */ Vec3f focalActorAtOffset; // Offset between the camera's at Pos and the focalActor's Pos
+    /* 0x0F0 */ Vec3f unk_0F0; // Offset between the focalActor's Pos and the camera's focalActor's Pos from the previous frame
     /* 0x0FC */ f32 fov;
     /* 0x100 */ f32 atLerpStepScale;
-    /* 0x104 */ f32 playerFloorHeight;
+    /* 0x104 */ f32 focalActorFloorHeight;
     /* 0x108 */ Vec3f floorNorm;
     /* 0x114 */ f32 waterYPos;
     /* 0x118 */ s32 waterPrevBgCamDataId;
@@ -1588,11 +1588,11 @@ typedef struct Camera {
     /* 0x142 */ s16 setting;
     /* 0x144 */ s16 mode;
     /* 0x146 */ s16 bgId;
-    /* 0x148 */ s16 bgCamDataId;
+    /* 0x148 */ s16 bgCamIndex;
     /* 0x14A */ s16 behaviorFlags;
     /* 0x14C */ s16 stateFlags;
     /* 0x14E */ s16 childCamId;
-    /* 0x150 */ s16 doorTimer1; // a door timer used when door cam is indexed from bgCamDataId
+    /* 0x150 */ s16 doorTimer1; // a door timer used when door cam is indexed from bgCamIndex
     /* 0x152 */ s16 unk152;
     /* 0x154 */ s16 prevSetting;
     /* 0x156 */ s16 nextCamSceneDataId;
@@ -1600,8 +1600,8 @@ typedef struct Camera {
     /* 0x15A */ s16 roll;
     /* 0x15C */ s16 viewFlags;
     /* 0x15E */ s16 animState; // Determines the current state of the current camera behavior function
-    /* 0x160 */ s16 unk160;
-    /* 0x162 */ s16 doorTimer2; // a door timer used when door cam is indexed from bgCamDataId
+    /* 0x160 */ s16 timer; // Unused remnant of OoT: originally destoryed subCamera when timer ran out
+    /* 0x162 */ s16 doorTimer2; // a door timer used when door cam is indexed from bgCamIndex
     /* 0x164 */ s16 camId;
     /* 0x166 */ s16 prevBgCamDataId;
     /* 0x168 */ s16 unk168;

include/z64player.h

@@ -677,7 +677,7 @@ typedef enum PlayerCsMode {
 #define PLAYER_STATE1_1          (1 << 0)
 // 
 #define PLAYER_STATE1_2          (1 << 1)
-// 
+// Climbing ledge
 #define PLAYER_STATE1_4          (1 << 2)
 // 
 #define PLAYER_STATE1_8          (1 << 3)
@@ -697,7 +697,7 @@ typedef enum PlayerCsMode {
 #define PLAYER_STATE1_400        (1 << 10)
 // 
 #define PLAYER_STATE1_800        (1 << 11)
-// 
+// charging spin attack
 #define PLAYER_STATE1_1000       (1 << 12)
 // 
 #define PLAYER_STATE1_2000       (1 << 13)
@@ -731,7 +731,7 @@ typedef enum PlayerCsMode {
 #define PLAYER_STATE1_8000000    (1 << 27)
 // 
 #define PLAYER_STATE1_10000000   (1 << 28)
-// 
+// Time is stopped but Link & NPC animations continue
 #define PLAYER_STATE1_20000000   (1 << 29)
 // 
 #define PLAYER_STATE1_40000000   (1 << 30)
@@ -761,7 +761,7 @@ typedef enum PlayerCsMode {
 #define PLAYER_STATE2_200        (1 << 9)
 // 
 #define PLAYER_STATE2_400        (1 << 10)
-// 
+// Diving
 #define PLAYER_STATE2_800        (1 << 11)
 // 
 #define PLAYER_STATE2_1000       (1 << 12)
@@ -773,7 +773,7 @@ typedef enum PlayerCsMode {
 #define PLAYER_STATE2_8000       (1 << 15)
 // 
 #define PLAYER_STATE2_10000      (1 << 16)
-// 
+// A non-magic spin attack
 #define PLAYER_STATE2_20000      (1 << 17)
 // 
 #define PLAYER_STATE2_40000      (1 << 18)
@@ -821,7 +821,7 @@ typedef enum PlayerCsMode {
 #define PLAYER_STATE3_40         (1 << 6)
 // 
 #define PLAYER_STATE3_80         (1 << 7)
-// Related to form Deku
+// Deku flower dive
 #define PLAYER_STATE3_100        (1 << 8)
 // 
 #define PLAYER_STATE3_200        (1 << 9)