Some doc on env light settings (#1307)

* remove `LightSettings` struct, typedef for zapd

* more decimal

* fog far -> z far

* `LIGHTCTX_FOGNEAR_MAX`, `LIGHTCTX_ZFAR_MAX`

* name sp88,sp8C in `Environment_Update`

* `EnvLightSettings.fogNear` -> `blendRateAndFogNear` and macros

* A different struct for `EnvironmentContext.lightSettings`

* Uniform zapd compat typedefs todos

* `LIGHTCTX_` -> `ENV_`

* Comment on `blendRateAndFogNear` + "fogFar"

* Move fogFar~1000 comment to zFar

* comment rewrite attempt

* move relevant macros down

Co-authored-by: fig02 <fig02srl@gmail.com>

include/functions.h

@@ -911,7 +911,7 @@ void Lights_Draw(Lights* lights, GraphicsContext* gfxCtx);
 void Lights_BindAll(Lights* lights, LightNode* listHead, Vec3f* vec);
 void LightContext_Init(PlayState* play, LightContext* lightCtx);
 void LightContext_SetAmbientColor(LightContext* lightCtx, u8 r, u8 g, u8 b);
-void LightContext_SetFog(LightContext* lightCtx, u8 r, u8 g, u8 b, s16 fogNear, s16 fogFar);
+void LightContext_SetFog(LightContext* lightCtx, u8 r, u8 g, u8 b, s16 fogNear, s16 zFar);
 Lights* LightContext_NewLights(LightContext* lightCtx, GraphicsContext* gfxCtx);
 void LightContext_InitList(PlayState* play, LightContext* lightCtx);
 void LightContext_DestroyList(PlayState* play, LightContext* lightCtx);

include/regs.h

@@ -43,7 +43,7 @@
 #define R_ENV_LIGHT2_COLOR(i)                    REG(6 + (i))
 #define R_ENV_DISABLE_DBG                        REG(9)
 #define R_ENV_FOG_COLOR(i)                       REG(10 + (i))
-#define R_ENV_FOG_FAR                            REG(13)
+#define R_ENV_Z_FAR                              REG(13)
 #define R_ENV_FOG_NEAR                           REG(14)
 #define R_ENV_TIME_SPEED_OLD                     REG(15) // Most likely used during development. Unused in the final game.
 #define R_RUN_SPEED_LIMIT                        REG(45)

include/z64bgcheck.h

@@ -55,7 +55,9 @@ typedef struct {
     /* 0x4 */ Vec3s* bgCamFuncData; // s16 data grouped in threes (ex. Vec3s), is usually of type `BgCamFuncData`, but can be a list of points of type `Vec3s` for crawlspaces
 } BgCamInfo; // size = 0x8
 
-typedef BgCamInfo CamData; // Todo: Zapd compatibility
+// ZAPD compatibility typedefs
+// TODO: Remove when ZAPD adds support for them
+typedef BgCamInfo CamData;
 
 // The structure used for all instances of s16 data from `BgCamInfo` with the exception of crawlspaces.
 // See `Camera_Subj4` for Vec3s data usage in crawlspaces

include/z64environment.h

@@ -139,10 +139,34 @@ typedef struct {
     /* 0x09 */ s8 light2Dir[3];
     /* 0x0C */ u8 light2Color[3];
     /* 0x0F */ u8 fogColor[3];
-    /* 0x12 */ s16 fogNear;
-    /* 0x14 */ s16 fogFar;
+    /* 0x12 */ s16 fogNear; // ranges from 0-1000 (0: starts immediately, 1000: no fog), but is clamped to ENV_FOGNEAR_MAX
+    /* 0x14 */ s16 zFar; // Max depth (render distance) of the view as a whole. fogFar will always match zFar
+} CurrentEnvLightSettings; // size = 0x16
+
+// `EnvLightSettings` is very similar to `CurrentEnvLightSettings` with one key difference.
+// The light settings data in the scene packs blend rate information with the fog near value.
+// The blendRate determines how fast the current light settings fade to the next one 
+// (under LIGHT_MODE_SETTINGS, otherwise unused). 
+
+// Get blend rate from `EnvLightSettings.blendRateAndFogNear` in 0-255 range
+#define ENV_LIGHT_SETTINGS_BLEND_RATE_U8(blendRateAndFogNear) (((blendRateAndFogNear) >> 10) * 4)
+#define ENV_LIGHT_SETTINGS_FOG_NEAR(blendRateAndFogNear) ((blendRateAndFogNear) & 0x3FF)
+
+typedef struct {
+    /* 0x00 */ u8 ambientColor[3];
+    /* 0x03 */ s8 light1Dir[3];
+    /* 0x06 */ u8 light1Color[3];
+    /* 0x09 */ s8 light2Dir[3];
+    /* 0x0C */ u8 light2Color[3];
+    /* 0x0F */ u8 fogColor[3];
+    /* 0x12 */ s16 blendRateAndFogNear; 
+    /* 0x14 */ s16 zFar;
 } EnvLightSettings; // size = 0x16
 
+// ZAPD compatibility typedefs
+// TODO: Remove when ZAPD adds support for them
+typedef EnvLightSettings LightSettings;
+
 typedef struct {
     /* 0x00 */ char unk_00[0x02];
     /* 0x02 */ u16 sceneTimeSpeed; // time speed value from the scene file
@@ -178,7 +202,7 @@ typedef struct {
     /* 0x92 */ s16 adjLight1Color[3];
     /* 0x98 */ s16 adjFogColor[3];
     /* 0x9E */ s16 adjFogNear;
-    /* 0xA0 */ s16 adjFogFar;
+    /* 0xA0 */ s16 adjZFar;
     /* 0xA2 */ char unk_A2[0x06];
     /* 0xA8 */ Vec3s windDirection;
     /* 0xB0 */ f32 windSpeed;
@@ -188,7 +212,7 @@ typedef struct {
     /* 0xBD */ u8 lightSetting; // only used with `LIGHT_MODE_SETTINGS` or on override
     /* 0xBE */ u8 prevLightSetting;
     /* 0xBF */ u8 lightSettingOverride;
-    /* 0xC0 */ EnvLightSettings lightSettings; // settings for the currently "live" lights
+    /* 0xC0 */ CurrentEnvLightSettings lightSettings; // settings for the currently "live" lights
     /* 0xD6 */ u16 lightBlendRateOverride;
     /* 0xD8 */ f32 lightBlend; // only used with `LIGHT_MODE_SETTINGS` or on setting override
     /* 0xDC */ u8 lightBlendOverride;

include/z64light.h

@@ -43,12 +43,15 @@ typedef struct LightNode {
     /* 0x8 */ struct LightNode* next;
 } LightNode; // size = 0xC
 
+#define ENV_FOGNEAR_MAX 996
+#define ENV_ZFAR_MAX 12800
+
 typedef struct {
     /* 0x0 */ LightNode* listHead;
     /* 0x4 */ u8 ambientColor[3];
     /* 0x7 */ u8 fogColor[3];
-    /* 0xA */ s16 fogNear; // how close until fog starts taking effect. range 0 - 1000
-    /* 0xC */ s16 fogFar; // how far until fog starts to saturate. range 0 - 1000
+    /* 0xA */ s16 fogNear; // how close until fog starts taking effect. range 0 - ENV_FOGNEAR_MAX
+    /* 0xC */ s16 zFar; // draw distance. range 0 - ENV_ZFAR_MAX
 } LightContext; // size = 0x10
 
 typedef enum {

include/z64scene.h

@@ -45,17 +45,6 @@ typedef struct {
 // TODO: ZAPD Compatibility
 typedef Spawn EntranceEntry; 
 
-typedef struct {
-    /* 0x00 */ u8 ambientColor[3];
-    /* 0x03 */ s8 diffuseDir1[3];
-    /* 0x06 */ u8 diffuseColor1[3];
-    /* 0x09 */ s8 diffuseDir2[3];
-    /* 0x0C */ u8 diffuseColor2[3];
-    /* 0x0F */ u8 fogColor[3];
-    /* 0x12 */ u16 fogNear;
-    /* 0x14 */ u16 fogFar;
-} LightSettings; // size = 0x16
-
 typedef struct {
     /* 0x00 */ u8 count; // number of points in the path
     /* 0x04 */ Vec3s* points; // Segment Address to the array of points
@@ -157,7 +146,8 @@ typedef union {
     RoomShapeCullable cullable;
 } RoomShape; // "Ground Shape"
 
-// TODO update ZAPD
+// ZAPD compatibility typedefs
+// TODO: Remove when ZAPD adds support for them
 typedef RoomShapeDListsEntry PolygonDlist;
 typedef RoomShapeNormal PolygonType0;
 typedef RoomShapeImageSingle MeshHeader1Single;