Lens docs (#1123)

* match MirRay_ReflectedBeam

* match Actor_DrawLensActors

* match func_80B9E8D4

* lens docs

* more lens docs

* fix

* cleanup

* move define down

* Actor_AddToLensActors

* small comment adj

* add one more comment

* fix bss

include/functions.h

@@ -721,7 +721,7 @@ void Actor_DeactivateLens(PlayState* play);
 void func_800B9120(ActorContext* actorCtx);
 void Actor_InitContext(PlayState* play, ActorContext* actorCtx, ActorEntry* actorEntry);
 void Actor_UpdateAll(PlayState* play, ActorContext* actorCtx);
-s32 Actor_RecordUndrawnActor(PlayState* play, Actor* actor);
+s32 Actor_AddToLensActors(PlayState* play, Actor* actor);
 void Actor_DrawAll(PlayState* play, ActorContext* actorCtx);
 void func_800BA6FC(PlayState* play, ActorContext* actorCtx);
 void func_800BA798(PlayState* play, ActorContext* actorCtx);

include/z64.h

@@ -930,7 +930,7 @@ typedef struct PlayState {
     /* 0x18E5C */ TexturePtr pictoPhotoI8;
     /* 0x18E60 */ void* unk_18E60;
     /* 0x18E64 */ void* unk_18E64;
-    /* 0x18E68 */ void* unk_18E68;
+    /* 0x18E68 */ void* unk_18E68; // framebuffer related to Lens of Truth
     /* 0x18E6C */ char unk_18E6C[0x3EC];
 } PlayState; // size = 0x19258
 

include/z64actor.h

@@ -385,6 +385,13 @@ typedef struct ActorListEntry {
     /* 0x8 */ s32 unk_08;
 } ActorListEntry; // size = 0xC
 
+typedef enum {
+    /* 0 */ LENS_MODE_HIDE_ACTORS, // lens actors are visible by default, and hidden by using lens (for example, fake walls)
+    /* 1 */ LENS_MODE_SHOW_ACTORS // lens actors are invisible by default, and shown by using lens (for example, invisible enemies)
+} LensMode;
+
+#define LENS_ACTOR_MAX 32
+
 // Target size when activated
 #define LENS_MASK_ACTIVE_SIZE 100
 
@@ -399,9 +406,9 @@ typedef struct ActorContext {
     /* 0x00B */ s8 lensActorsDrawn;
     /* 0x00C */ s16 unkC;
     /* 0x00E */ u8 totalLoadedActors;
-    /* 0x00F */ u8 undrawnActorCount;
+    /* 0x00F */ u8 numLensActors;
     /* 0x010 */ ActorListEntry actorLists[ACTORCAT_MAX];
-    /* 0x0A0 */ Actor* undrawnActors[32]; // Records the first 32 actors drawn each frame
+    /* 0x0A0 */ Actor* lensActors[LENS_ACTOR_MAX]; // Draws up to LENS_ACTOR_MAX number of invisible actors
     /* 0x120 */ TargetContext targetContext;
     /* 0x1B8 */ ActorContextSceneFlags sceneFlags;
     /* 0x1E4 */ TitleCardContext titleCtxt;
@@ -467,8 +474,8 @@ typedef enum {
 #define ACTOR_FLAG_20            (1 << 5)
 // 
 #define ACTOR_FLAG_40            (1 << 6)
-// Invisible
-#define ACTOR_FLAG_80            (1 << 7)
+// hidden or revealed by Lens of Truth (depending on room lensMode)
+#define ACTOR_FLAG_REACT_TO_LENS (1 << 7)
 // Related to talk
 #define ACTOR_FLAG_100           (1 << 8)
 // 

include/z64scene.h

@@ -261,7 +261,7 @@ typedef struct {
     /* 0x02 */ u8 unk2; // 3: Room is hot
     /* 0x03 */ u8 unk3;
     /* 0x04 */ s8 echo;
-    /* 0x05 */ u8 unk5;
+    /* 0x05 */ u8 lensMode;
     /* 0x06 */ u8 enablePosLights;
     /* 0x07 */ UNK_TYPE1 pad7[0x1];
     /* 0x08 */ RoomMesh* mesh;