EnGe1 OK and documented, document z_snap (#952)

* Move PictoActor typedefs to z64actor.h

* OK, data imported

* Minor snap stuff

* Name most functions and variables

* Name most of object, apart from animations

* Document snap

* Fix actors to use the PictoActor struct

* Format

* Finish documenting EnGe1

* Finish documenting z_snap and related actors

* Format

* Review, format

* Name last couple of things

* bss

* Review

* Review

* bss

* Introduce z64snap.h, add SCREEN_TO_DEVICE macros

* Back to PROJECTED_TO_SCREEN

include/functions.h

@@ -594,7 +594,7 @@ void ActorShadow_DrawFeet(Actor* actor, Lights* mapper, PlayState* play);
 void Actor_SetFeetPos(Actor* actor, s32 limbIndex, s32 leftFootIndex, Vec3f* leftFootPos, s32 rightFootIndex, Vec3f* rightFootPos);
 void func_800B4AEC(PlayState* play, Actor* actor, f32 y);
 void func_800B4B50(Actor* actor, Lights* mapper, PlayState* play);
-void Actor_GetProjectedPos(PlayState* play, Vec3f* arg1, Vec3f* arg2, f32* arg3);
+void Actor_GetProjectedPos(PlayState* play, Vec3f* worldPos, Vec3f* projectedPos, f32* invW);
 
 void Actor_DrawZTarget(TargetContext* targetCtx, PlayState* play);
 
@@ -2345,13 +2345,6 @@ void SkinMatrix_SetYRotation(MtxF* mf, s16 a);
 void SkinMatrix_MulYRotation(MtxF* mf, s16 a);
 void SkinMatrix_SetZRotation(MtxF* mf, s16 a);
 
-s32 func_8013A240(PlayState* play);
-void func_8013A41C(s32 flag);
-void func_8013A46C(s32 flag);
-u32 func_8013A4C4(s32 flag);
-s16 func_8013A504(s16 val);
-s32 func_8013A530(PlayState* play, Actor* actor, s32 flag, Vec3f* pos, Vec3s* rot, f32 distanceMin, f32 distanceMax, s16 angleError);
-
 void View_ViewportToVp(Vp* dest, Viewport* src);
 void View_Init(View* view, GraphicsContext* gfxCtx);
 void View_SetViewOrientation(View* view, Vec3f* eye, Vec3f* at, Vec3f* up);

include/macros.h

@@ -11,6 +11,9 @@
 #define SCREEN_WIDTH_HIGH_RES  576
 #define SCREEN_HEIGHT_HIGH_RES 454
 
+#define PROJECTED_TO_SCREEN_X(projectedPos, invW) ((projectedPos).x * (invW) * (SCREEN_WIDTH / 2) + (SCREEN_WIDTH / 2))
+#define PROJECTED_TO_SCREEN_Y(projectedPos, invW) ((projectedPos).y * (invW) * (-SCREEN_HEIGHT / 2) + (SCREEN_HEIGHT / 2))
+
 #define ARRAY_COUNT(arr) (s32)(sizeof(arr) / sizeof(arr[0]))
 #define ARRAY_COUNTU(arr) (u32)(sizeof(arr) / sizeof(arr[0]))
 

include/z64actor.h

@@ -9,6 +9,7 @@
 
 // This value is hardcoded to be the size of ovl_Arrow_Fire which currently is the biggest actor that uses the AM_FIELD.
 #define AM_FIELD_SIZE SEGMENT_SIZE(ovl_Arrow_Fire)
+
 #define MASS_IMMOVABLE 0xFF // Cannot be pushed by OC collisions
 #define MASS_HEAVY 0xFE     // Can only be pushed by OC collisions with IMMOVABLE and HEAVY objects.
 
@@ -222,6 +223,7 @@ typedef struct {
     /* 0x15A */ s16 pad15A;
 } DynaPolyActor; // size = 0x15C
 
+
 typedef enum {
     /* 0x00 */ ITEM00_RUPEE_GREEN,
     /* 0x01 */ ITEM00_RUPEE_BLUE,

include/z64item.h

@@ -558,7 +558,7 @@ typedef enum {
 typedef enum {
     /*   -1 */ EXCH_ITEM_MINUS1 = -1, // Unknown usage or function
     /* 0x00 */ EXCH_ITEM_NONE,
-    /* 0x13 */ EXCH_ITEM_13 = 0x13,
+    /* 0x13 */ EXCH_ITEM_PICTO_BOX = 0x13,
     /* 0x1E */ EXCH_ITEM_1E = 0x1E, // BOTTLE_MUSHROOM
     /* 0x2A */ EXCH_ITEM_MOON_TEAR = 0x2A,
     /* 0x2B */ EXCH_ITEM_DEED_LAND,

include/z64save.h

@@ -143,8 +143,8 @@ typedef struct Save {
     /* 0x00F8 */ PermanentSceneFlags permanentSceneFlags[120];
     /* 0x0E18 */ u8 unk_E18[0x54];
     /* 0x0E6C */ u32 dekuPlaygroundHighScores[3];
-    /* 0x0E78 */ u32 pictoFlags0;
-    /* 0x0E7C */ u32 pictoFlags1;
+    /* 0x0E78 */ u32 pictoFlags0;                       // Flags set by `PictoActor`s if pictograph is valid
+    /* 0x0E7C */ u32 pictoFlags1;                       // Flags set by Snap_ValidatePictograph() to record errors; volatile since that function is run many times in succession
     /* 0x0E80 */ u32 unk_E80;
     /* 0x0E84 */ u32 unk_E84;
     /* 0x0E88 */ u32 unk_E88[7];                        // Invadepoh flags

include/z64snap.h

@@ -0,0 +1,52 @@
+#ifndef Z64_SNAP_H
+#define Z64_SNAP_H
+
+#include "PR/ultratypes.h"
+#include "z64actor.h"
+
+typedef s32 (*PictoValidationFunc)(struct PlayState*, Actor*);
+
+typedef struct {
+    /* 0x000 */ Actor actor;
+    /* 0x144 */ PictoValidationFunc validationFunc;
+} PictoActor;
+
+// Picto box flags
+
+typedef enum {
+    // Used externally, set and read by actors
+    /* 0x00 */ PICTOGRAPH_0,
+    /* 0x01 */ PICTOGRAPH_IN_SWAMP,
+    /* 0x02 */ PICTOGRAPH_MONKEY,
+    /* 0x03 */ PICTOGRAPH_BIG_OCTO,
+    /* 0x04 */ PICTOGRAPH_LULU_HEAD,
+    /* 0x05 */ PICTOGRAPH_LULU_RIGHT_ARM,
+    /* 0x06 */ PICTOGRAPH_LULU_LEFT_ARM, // Need all three of these to qualify as a good picture
+    /* 0x07 */ PICTOGRAPH_SCARECROW,
+    /* 0x08 */ PICTOGRAPH_TINGLE,
+    /* 0x09 */ PICTOGRAPH_PIRATE_GOOD,
+    /* 0x0A */ PICTOGRAPH_DEKU_KING,
+    /* 0x0B */ PICTOGRAPH_PIRATE_TOO_FAR, // overlaps with PICTOGRAPH_PIRATE_GOOD, but that is checked first
+
+    // Used internally, test for failures of position, angle etc.
+    /* 0x3B */ PICTOGRAPH_BEHIND_COLLISION = 0x3B,
+    /* 0x3C */ PICTOGRAPH_BEHIND_BG,
+    /* 0x3D */ PICTOGRAPH_NOT_IN_VIEW,
+    /* 0x3E */ PICTOGRAPH_BAD_ANGLE,
+    /* 0x3F */ PICTOGRAPH_BAD_DISTANCE
+} PictographFlag;
+
+// The following macros are subject to renaming once the capture system is better understood
+#define PICTO_RESOLUTION_HORIZONTAL 150
+#define PICTO_RESOLUTION_VERTICAL 105
+#define PICTO_CAPTURE_REGION_TOPLEFT_X ((SCREEN_WIDTH - PICTO_RESOLUTION_HORIZONTAL) / 2)
+#define PICTO_CAPTURE_REGION_TOPLEFT_Y ((SCREEN_HEIGHT - PICTO_RESOLUTION_VERTICAL) / 2)
+
+s32 Snap_RecordPictographedActors(PlayState* play);
+void Snap_SetFlag(s32 flag);
+void Snap_UnsetFlag(s32 flag);
+u32 Snap_CheckFlag(s32 flag);
+s16 Snap_AbsS(s16 val);
+s32 Snap_ValidatePictograph(PlayState* play, Actor* actor, s32 flag, Vec3f* pos, Vec3s* rot, f32 distanceMin, f32 distanceMax, s16 angleRange);
+
+#endif