Doc pass on bgcheck-waterbox properties (#1288)

* Doc pass on bgcheck-waterbox properties

* `WATERBOX_ROOM_INDEX...` -> `WATERBOX_ROOM...`

* Fix `WATERBOX_PROPERTIES` macro (was completely wrong)

* `((setFlag19) & 1) << WATERBOX_FLAG_19_SHIFT` instead of ternary

* Fix `WATERBOX_PROPERTIES` macro (hopefully for good)

include/functions.h

@@ -664,7 +664,7 @@ s32 WaterBox_GetSurfaceImpl(PlayState* play, CollisionContext* colCtx, f32 x, f3
                             WaterBox** outWaterBox);
 u32 WaterBox_GetBgCamIndex(CollisionContext* colCtx, WaterBox* waterBox);
 u16 WaterBox_GetBgCamSetting(CollisionContext* colCtx, WaterBox* waterBox);
-u32 WaterBox_GetLightSettingIndex(CollisionContext* colCtx, WaterBox* waterBox);
+u32 WaterBox_GetLightIndex(CollisionContext* colCtx, WaterBox* waterBox);
 s32 func_80042708(CollisionPoly* polyA, CollisionPoly* polyB, Vec3f* point, Vec3f* closestPoint);
 s32 func_800427B4(CollisionPoly* polyA, CollisionPoly* polyB, Vec3f* pointA, Vec3f* pointB, Vec3f* closestPoint);
 void BgCheck_DrawDynaCollision(PlayState*, CollisionContext*);

include/z64bgcheck.h

@@ -26,8 +26,6 @@ struct DynaPolyActor;
 #define FUNC_80041EA4_STOP 8
 #define FUNC_80041EA4_VOID_OUT 12
 
-#define WATERBOX_ROOM(p) ((p >> 13) & 0x3F)
-
 typedef struct {
     Vec3f scale;
     Vec3s rot;
@@ -73,6 +71,32 @@ typedef struct {
     /* 0x10 */ s16 unk_10; // unused
 } BgCamFuncData; // size = 0x12
 
+// Macros for `WaterBox.properties`
+
+#define WATERBOX_BGCAM_INDEX_SHIFT 0
+#define WATERBOX_BGCAM_INDEX_MASK 0x000000FF
+#define WATERBOX_BGCAM_INDEX(properties) \
+    (((properties) >> WATERBOX_BGCAM_INDEX_SHIFT) & (WATERBOX_BGCAM_INDEX_MASK >> WATERBOX_BGCAM_INDEX_SHIFT))
+
+#define WATERBOX_LIGHT_INDEX_SHIFT 8
+#define WATERBOX_LIGHT_INDEX_MASK 0x00001F00
+#define WATERBOX_LIGHT_INDEX(properties) \
+    (((properties) >> WATERBOX_LIGHT_INDEX_SHIFT) & (WATERBOX_LIGHT_INDEX_MASK >> WATERBOX_LIGHT_INDEX_SHIFT))
+#define WATERBOX_LIGHT_INDEX_NONE 0x1F // warns and defaults to 0
+
+#define WATERBOX_ROOM_SHIFT 13
+#define WATERBOX_ROOM_MASK 0x0007E000
+#define WATERBOX_ROOM(properties) (((properties) >> WATERBOX_ROOM_SHIFT) & (WATERBOX_ROOM_MASK >> WATERBOX_ROOM_SHIFT))
+#define WATERBOX_ROOM_ALL 0x3F // value for "room index" indicating "all rooms"
+
+#define WATERBOX_FLAG_19_SHIFT 19
+#define WATERBOX_FLAG_19 (1 << WATERBOX_FLAG_19_SHIFT)
+
+#define WATERBOX_PROPERTIES(bgCamIndex, lightIndex, room, setFlag19)              \
+    ((((bgCamIndex) << WATERBOX_BGCAM_INDEX_SHIFT) & WATERBOX_BGCAM_INDEX_MASK) | \
+     (((lightIndex) << WATERBOX_LIGHT_INDEX_SHIFT) & WATERBOX_LIGHT_INDEX_MASK) | \
+     (((room) << WATERBOX_ROOM_SHIFT) & WATERBOX_ROOM_MASK) | (((setFlag19) & 1) << WATERBOX_FLAG_19_SHIFT))
+
 typedef struct {
     /* 0x00 */ s16 xMin;
     /* 0x02 */ s16 ySurface;
@@ -80,11 +104,6 @@ typedef struct {
     /* 0x06 */ s16 xLength;
     /* 0x08 */ s16 zLength;
     /* 0x0C */ u32 properties;
-
-    // 0x0008_0000 = ?
-    // 0x0007_E000 = Room Index, 0x3F = all rooms
-    // 0x0000_1F00 = Lighting Settings Index
-    // 0x0000_00FF = BgCam Index
 } WaterBox; // size = 0x10
 
 typedef enum {

src/code/z_bgcheck.c

@@ -4174,9 +4174,9 @@ s32 WaterBox_GetSurfaceImpl(PlayState* play, CollisionContext* colCtx, f32 x, f3
 
     for (curWaterBox = colHeader->waterBoxes; curWaterBox < colHeader->waterBoxes + colHeader->numWaterBoxes;
          curWaterBox++) {
-        room = (curWaterBox->properties >> 13) & 0x3F;
+        room = WATERBOX_ROOM(curWaterBox->properties);
-        if (room == (u32)play->roomCtx.curRoom.num || room == 0x3F) {
+        if (room == (u32)play->roomCtx.curRoom.num || room == WATERBOX_ROOM_ALL) {
-            if ((curWaterBox->properties & 0x80000) == 0) {
+            if (!(curWaterBox->properties & WATERBOX_FLAG_19)) {
                 if (curWaterBox->xMin < x && x < curWaterBox->xMin + curWaterBox->xLength) {
                     if (curWaterBox->zMin < z && z < curWaterBox->zMin + curWaterBox->zLength) {
                         *outWaterBox = curWaterBox;
@@ -4191,7 +4191,7 @@ s32 WaterBox_GetSurfaceImpl(PlayState* play, CollisionContext* colCtx, f32 x, f3
 }
 
 /**
- * Gets the first active WaterBox at `pos` where WaterBox.properties & 0x80000 == 0
+ * Gets the first active WaterBox at `pos` with WATERBOX_FLAG_19 not set
  * `surfaceChkDist` is the absolute y distance from the water surface to check
  * returns the index of the waterbox found, or -1 if no waterbox is found
  * `outWaterBox` returns the pointer to the waterbox found, or NULL if none is found
@@ -4213,10 +4213,10 @@ s32 WaterBox_GetSurface2(PlayState* play, CollisionContext* colCtx, Vec3f* pos,
         waterBox = &colHeader->waterBoxes[i];
 
         room = WATERBOX_ROOM(waterBox->properties);
-        if (!(room == play->roomCtx.curRoom.num || room == 0x3F)) {
+        if (!(room == play->roomCtx.curRoom.num || room == WATERBOX_ROOM_ALL)) {
             continue;
         }
-        if (waterBox->properties & 0x80000) {
+        if (waterBox->properties & WATERBOX_FLAG_19) {
             continue;
         }
         if (!(waterBox->xMin < pos->x && pos->x < waterBox->xMin + waterBox->xLength)) {
@@ -4239,9 +4239,9 @@ s32 WaterBox_GetSurface2(PlayState* play, CollisionContext* colCtx, Vec3f* pos,
  * WaterBox get BgCam index
  */
 u32 WaterBox_GetBgCamIndex(CollisionContext* colCtx, WaterBox* waterBox) {
-    u32 prop = waterBox->properties >> 0;
+    u32 bgCamIndex = WATERBOX_BGCAM_INDEX(waterBox->properties);
 
-    return prop & 0xFF;
+    return bgCamIndex;
 }
 
 /**
@@ -4261,15 +4261,15 @@ u16 WaterBox_GetBgCamSetting(CollisionContext* colCtx, WaterBox* waterBox) {
 /**
  * WaterBox get lighting settings
  */
-u32 WaterBox_GetLightSettingIndex(CollisionContext* colCtx, WaterBox* waterBox) {
+u32 WaterBox_GetLightIndex(CollisionContext* colCtx, WaterBox* waterBox) {
-    u32 prop = waterBox->properties >> 8;
+    u32 lightIndex = WATERBOX_LIGHT_INDEX(waterBox->properties);
 
-    return prop & 0x1F;
+    return lightIndex;
 }
 
 /**
  * Get the water surface at point (`x`, `ySurface`, `z`). `ySurface` doubles as position y input
- * same as WaterBox_GetSurfaceImpl, but tests if WaterBox properties & 0x80000 != 0
+ * same as WaterBox_GetSurfaceImpl, but tests if WATERBOX_FLAG_19 is set
  * returns true if point is within the xz boundaries of an active water box, else false
  * `ySurface` returns the water box's surface, while `outWaterBox` returns a pointer to the WaterBox
  */
@@ -4284,9 +4284,9 @@ s32 func_800425B0(PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32*
 
     for (curWaterBox = colHeader->waterBoxes; curWaterBox < colHeader->waterBoxes + colHeader->numWaterBoxes;
          curWaterBox++) {
-        room = (curWaterBox->properties >> 0xD) & 0x3F;
+        room = WATERBOX_ROOM(curWaterBox->properties);
-        if ((room == (u32)play->roomCtx.curRoom.num) || (room == 0x3F)) {
+        if ((room == (u32)play->roomCtx.curRoom.num) || (room == WATERBOX_ROOM_ALL)) {
-            if ((curWaterBox->properties & 0x80000) != 0) {
+            if (curWaterBox->properties & WATERBOX_FLAG_19) {
                 if (curWaterBox->xMin < x && x < (curWaterBox->xMin + curWaterBox->xLength)) {
                     if (curWaterBox->zMin < z && z < (curWaterBox->zMin + curWaterBox->zLength)) {
                         *outWaterBox = curWaterBox;

src/code/z_camera.c

@@ -540,11 +540,11 @@ s32 Camera_GetWaterBoxBgCamIndex(Camera* camera, f32* waterY) {
 }
 
 /**
- * Checks if `chkPos` is inside a waterbox. If there is no water box below `chkPos`
+ * Checks if `chkPos` is inside a waterbox.
- * or if `chkPos` is above the water surface, return BGCHECK_Y_MIN, output
+ * If there is no water box below `chkPos` or if `chkPos` is above the water surface, return BGCHECK_Y_MIN.
- * environment properites to `envProp` if `chkPos` is inside the waterbox.
+ * If `chkPos` is inside the waterbox, output light index to `lightIndex`.
  */
-f32 Camera_GetWaterSurface(Camera* camera, Vec3f* chkPos, s32* envProp) {
+f32 Camera_GetWaterSurface(Camera* camera, Vec3f* chkPos, s32* lightIndex) {
     PosRot playerPosRot;
     f32 waterY;
     WaterBox* waterBox;
@@ -563,7 +563,7 @@ f32 Camera_GetWaterSurface(Camera* camera, Vec3f* chkPos, s32* envProp) {
         return BGCHECK_Y_MIN;
     }
 
-    *envProp = WaterBox_GetLightSettingIndex(&camera->play->colCtx, waterBox);
+    *lightIndex = WaterBox_GetLightIndex(&camera->play->colCtx, waterBox);
     return waterY;
 }
 

src/code/z_kankyo.c

@@ -783,7 +783,7 @@ void Environment_UpdateSkybox(u8 skyboxId, EnvironmentContext* envCtx, SkyboxCon
 }
 
 void Environment_EnableUnderwaterLights(PlayState* play, s32 waterLightsIndex) {
-    if (waterLightsIndex == 0x1F) {
+    if (waterLightsIndex == WATERBOX_LIGHT_INDEX_NONE) {
         waterLightsIndex = 0;
         // "Underwater color is not set in the water poly data!"
         osSyncPrintf(VT_COL(YELLOW, BLACK) "\n水ポリゴンデータに水中カラーが設定されておりません!" VT_RST);