Skip to content

Commit

Permalink
[zret] Port some documentation changes (HarbourMasters#1164)
Browse files Browse the repository at this point in the history
* zret: Documentation pass on scene/room commands HarbourMasters#1226

* Update OTR scene

* zret: Document the lens system HarbourMasters#1079

* zret: Misc. doc/cleanup 4 HarbourMasters#1093

* zret: Fix misc 8 HarbourMasters#1150

* zret: Document Distortions from z_camera and z_view HarbourMasters#1102
  • Loading branch information
dcvz authored and louist103 committed Aug 19, 2022
1 parent 84f6b77 commit a28d439
Show file tree
Hide file tree
Showing 73 changed files with 901 additions and 836 deletions.
18 changes: 9 additions & 9 deletions soh/include/functions.h
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ OSPiHandle* osDriveRomInit(void);
void StackCheck_Init(StackEntry* entry, void* stackTop, void* stackBottom, u32 initValue, s32 minSpace,
const char* name);
void StackCheck_Cleanup(StackEntry* entry);
StackStatus StackCheck_GetState(StackEntry* entry);
s32 StackCheck_GetState(StackEntry* entry);
u32 StackCheck_CheckAll(void);
u32 StackCheck_Check(StackEntry* entry);
f32 LogUtils_CheckFloatRange(const char* exp, s32 line, const char* valueName, f32 value, const char* minName, f32 min,
Expand Down Expand Up @@ -477,7 +477,7 @@ void func_8002F948(Actor* actor, u16 sfxId);
void func_8002F974(Actor* actor, u16 sfxId);
void func_8002F994(Actor* actor, s32 arg1);
s32 func_8002F9EC(GlobalContext* globalCtx, Actor* actor, CollisionPoly* poly, s32 bgId, Vec3f* pos);
void func_800304B0(GlobalContext* globalCtx);
void Actor_DisableLens(GlobalContext* globalCtx);
void func_800304DC(GlobalContext* globalCtx, ActorContext* actorCtx, ActorEntry* actorEntry);
void Actor_UpdateAll(GlobalContext* globalCtx, ActorContext* actorCtx);
s32 func_800314D4(GlobalContext* globalCtx, Actor* actorB, Vec3f* arg2, f32 arg3);
Expand Down Expand Up @@ -1357,13 +1357,13 @@ void func_800AA4A8(View* view, f32 fovy, f32 near, f32 far);
void func_800AA4E0(View* view, f32* fovy, f32* near, f32* far);
void View_SetViewport(View* view, Viewport* viewport);
void View_GetViewport(View* view, Viewport* viewport);
void func_800AA76C(View* view, f32 arg1, f32 arg2, f32 arg3);
void func_800AA78C(View* view, f32 arg1, f32 arg2, f32 arg3);
s32 func_800AA7AC(View* view, f32 arg1);
void func_800AA7B8(View* view);
void func_800AA814(View* view);
void func_800AA840(View* view, Vec3f vec1, Vec3f vec2, f32 arg3);
s32 func_800AA890(View* view, Mtx* mtx);
void View_SetDistortionOrientation(View* view, f32 rotX, f32 rotY, f32 rotZ);
void View_SetDistortionScale(View* view, f32 scaleX, f32 scaleY, f32 scaleZ);
s32 View_SetDistortionSpeed(View* view, f32 speed);
void View_InitDistortion(View* view);
void View_ClearDistortion(View* view);
void View_SetDistortion(View* view, Vec3f orientation, Vec3f scale, f32 speed);
s32 View_StepDistortion(View* view, Mtx* projectionMtx);
void func_800AAA50(View* view, s32 arg1);
s32 func_800AAA9C(View* view);
s32 func_800AB0A8(View* view);
Expand Down
2 changes: 1 addition & 1 deletion soh/include/variables.h
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ extern "C"
extern void* gItemIcons[0x82];
extern u8 gItemAgeReqs[];
extern u8 gItemSlots[56];
extern void (*gSceneCmdHandlers[26])(GlobalContext*, SceneCmd*);
extern void (*gSceneCmdHandlers[SCENE_CMD_ID_MAX])(GlobalContext*, SceneCmd*);
extern s16 gLinkObjectIds[2];
extern u32 gObjectTableSize;
extern RomFile gObjectTable[OBJECT_ID_MAX];
Expand Down
64 changes: 42 additions & 22 deletions soh/include/z64.h
Original file line number Diff line number Diff line change
Expand Up @@ -202,11 +202,11 @@ typedef struct {
/* 0x00A0 */ Mtx viewing;
/* 0x00E0 */ Mtx* projectionPtr;
/* 0x00E4 */ Mtx* viewingPtr;
/* 0x00E8 */ Vec3f unk_E8;
/* 0x00F4 */ Vec3f unk_F4;
/* 0x0100 */ f32 unk_100;
/* 0x0104 */ Vec3f unk_104;
/* 0x0110 */ Vec3f unk_110;
/* 0x00E8 */ Vec3f distortionOrientation;
/* 0x00F4 */ Vec3f distortionScale;
/* 0x0100 */ f32 distortionSpeed;
/* 0x0104 */ Vec3f curDistortionOrientation;
/* 0x0110 */ Vec3f curDistortionScale;
/* 0x011C */ u16 normal; // used to normalize the projection matrix
/* 0x0120 */ s32 flags;
/* 0x0124 */ s32 unk_124;
Expand Down Expand Up @@ -273,11 +273,10 @@ typedef struct {
/* 0x0000 */ u8 freezeFlashTimer;
/* 0x0001 */ char unk_01[0x01];
/* 0x0002 */ u8 unk_02;
/* 0x0003 */ u8 unk_03;
/* 0x0003 */ u8 lensActive;
/* 0x0004 */ char unk_04[0x04];
/* 0x0008 */ u8 total; // total number of actors loaded
/* 0x0009 */ char unk_09[0x03];
/* 0x000C */ ActorListEntry actorLists[12];
/* 0x000C */ ActorListEntry actorLists[ACTORCAT_MAX];
/* 0x006C */ TargetContext targetCtx;
struct {
/* 0x0104 */ u32 swch;
Expand Down Expand Up @@ -890,13 +889,10 @@ void* xluDL;

typedef struct {
/* 0x00 */ u8 type;
/* 0x01 */ u8 num; // number of dlist entries
/* 0x04 */ void* start;
/* 0x08 */ void* end;
} Polygon; // size = 0xC
} PolygonBase;

typedef struct {
/* 0x00 */ u8 type;
/* 0x00 */ PolygonBase base;
/* 0x01 */ u8 num; // number of dlist entries
/* 0x04 */ void* start;
/* 0x08 */ void* end;
Expand All @@ -917,7 +913,7 @@ typedef struct {
} BgImage; // size = 0x1C

typedef struct {
/* 0x00 */ u8 type;
/* 0x00 */ PolygonBase base;
/* 0x01 */ u8 format; // 1 = single, 2 = multi
/* 0x04 */ Gfx* dlist;
union {
Expand Down Expand Up @@ -955,27 +951,51 @@ typedef struct {
} PolygonDlist2; // size = 0x8

typedef struct {
/* 0x00 */ u8 type;
/* 0x00 */ PolygonBase base;
/* 0x01 */ u8 num; // number of dlist entries
/* 0x04 */ void* start;
/* 0x08 */ void* end;
} PolygonType2; // size = 0xC

typedef union {
Polygon polygon;
PolygonBase base;
PolygonType0 polygon0;
PolygonType1 polygon1;
PolygonType2 polygon2;
} Mesh; // "Ground Shape"
} MeshHeader; // "Ground Shape"

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;

typedef enum {
/* 0 */ ROOM_BEHAVIOR_TYPE1_0,
/* 1 */ ROOM_BEHAVIOR_TYPE1_1,
/* 2 */ ROOM_BEHAVIOR_TYPE1_2,
/* 3 */ ROOM_BEHAVIOR_TYPE1_3, // unused
/* 4 */ ROOM_BEHAVIOR_TYPE1_4, // unused
/* 5 */ ROOM_BEHAVIOR_TYPE1_5
} RoomBehaviorType1;

typedef enum {
/* 0 */ ROOM_BEHAVIOR_TYPE2_0,
/* 1 */ ROOM_BEHAVIOR_TYPE2_1,
/* 2 */ ROOM_BEHAVIOR_TYPE2_2,
/* 3 */ ROOM_BEHAVIOR_TYPE2_3,
/* 4 */ ROOM_BEHAVIOR_TYPE2_4,
/* 5 */ ROOM_BEHAVIOR_TYPE2_5,
/* 6 */ ROOM_BEHAVIOR_TYPE2_6
} RoomBehaviorType2;

typedef struct {
/* 0x00 */ s8 num;
/* 0x01 */ u8 unk_01;
/* 0x02 */ u8 unk_02;
/* 0x03 */ u8 unk_03;
/* 0x02 */ u8 behaviorType2;
/* 0x03 */ u8 behaviorType1;
/* 0x04 */ s8 echo;
/* 0x05 */ u8 showInvisActors;
/* 0x08 */ Mesh* mesh; // original name: "ground_shape"
/* 0x05 */ u8 lensMode;
/* 0x08 */ MeshHeader* meshHeader; // original name: "ground_shape"
/* 0x0C */ void* segment;
/* 0x10 */ char unk_10[0x4];
} Room; // size = 0x14
Expand Down Expand Up @@ -1244,7 +1264,7 @@ typedef struct GlobalContext {
/* 0x11DF0 */ RomFile* roomList;
/* 0x11DF4 */ ActorEntry* linkActorEntry;
/* 0x11DF8 */ ActorEntry* setupActorList;
/* 0x11DFC */ UNK_PTR unk_11DFC;
/* 0x11DFC */ void* unk_11DFC;
/* 0x11E00 */ EntranceEntry* setupEntranceList;
/* 0x11E04 */ s16* setupExitList;
/* 0x11E08 */ Path* setupPathList;
Expand Down
7 changes: 4 additions & 3 deletions soh/include/z64actor.h
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ typedef struct {

typedef struct {
/* 0x00 */ DamageTable* damageTable;
/* 0x04 */ Vec3f displacement; // Amount to correct velocity (0x5C) by when colliding into a body
/* 0x04 */ Vec3f displacement; // Amount to correct actor velocity by when colliding into a body
/* 0x10 */ s16 cylRadius; // Used for various purposes
/* 0x12 */ s16 cylHeight; // Used for various purposes
/* 0x14 */ s16 cylYShift; // Unused. Purpose inferred from Cylinder16 and CollisionCheck_CylSideVsLineSeg
Expand Down Expand Up @@ -158,7 +158,7 @@ typedef struct Actor {
/* 0x084 */ f32 yDistToWater; // Distance to the surface of active waterbox. Negative value means above water
/* 0x088 */ u16 bgCheckFlags; // See comments below actor struct for wip docs. TODO: macros for these flags
/* 0x08A */ s16 yawTowardsPlayer; // Y rotation difference between the actor and the player
/* 0x08C */ f32 xyzDistToPlayerSq; // Squared distance between the actor and the player in the x,y,z axis
/* 0x08C */ f32 xyzDistToPlayerSq; // Squared distance between the actor and the player
/* 0x090 */ f32 xzDistToPlayer; // Distance between the actor and the player in the XZ plane
/* 0x094 */ f32 yDistToPlayer; // Dist is negative if the actor is above the player
/* 0x098 */ CollisionCheckInfo colChkInfo; // Variables related to the Collision Check system
Expand Down Expand Up @@ -338,7 +338,8 @@ typedef enum {
/* 0x08 */ ACTORCAT_MISC,
/* 0x09 */ ACTORCAT_BOSS,
/* 0x0A */ ACTORCAT_DOOR,
/* 0x0B */ ACTORCAT_CHEST
/* 0x0B */ ACTORCAT_CHEST,
/* 0x0C */ ACTORCAT_MAX
} ActorCategory;

//#define DEFINE_ACTOR(_0, enum, _2) enum,
Expand Down
12 changes: 6 additions & 6 deletions soh/include/z64animation.h
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ typedef enum {
/* 3 */ ANIMMODE_ONCE_INTERP,
/* 4 */ ANIMMODE_LOOP_PARTIAL,
/* 5 */ ANIMMODE_LOOP_PARTIAL_INTERP
} AnimationModes;
} AnimationMode;

typedef enum {
/* -1 */ ANIMTAPER_DECEL = -1,
Expand Down Expand Up @@ -241,21 +241,21 @@ typedef s32 (*AnimUpdateFunc)();

typedef struct SkelAnime {
/* 0x00 */ u8 limbCount; // Number of limbs in the skeleton
/* 0x01 */ u8 mode; // 0: loop, 2: play once, 4: partial loop. +1 to interpolate between frames.
/* 0x01 */ u8 mode; // See `AnimationMode`
/* 0x02 */ u8 dListCount; // Number of display lists in a flexible skeleton
/* 0x03 */ s8 taper; // Tapering to use when morphing between animations. Only used by Door_Warp1.
/* 0x04 */ void** skeleton; // An array of pointers to limbs. Can be StandardLimb, LodLimb, or SkinLimb.
/* 0x08 */ void* animation; // Can be an AnimationHeader or LinkAnimationHeader.
/* 0x0C */ f32 startFrame; // In mode 4, start of partial loop.
/* 0x10 */ f32 endFrame; // In mode 2, Update returns true when curFrame is equal to this. In mode 4, end of partial loop.
/* 0x14 */ f32 animLength; // Total number of frames in the current animation's file.
/* 0x0C */ f32 startFrame; // In mode ANIMMODE_LOOP_PARTIAL*, start of partial loop.
/* 0x10 */ f32 endFrame; // In mode ANIMMODE_ONCE*, Update returns true when curFrame is equal to this. In mode ANIMMODE_LOOP_PARTIAL*, end of partial loop.
/* 0x14 */ f32 animLength; // Total number of frames in the current animation.
/* 0x18 */ f32 curFrame; // Current frame in the animation
/* 0x1C */ f32 playSpeed; // Multiplied by R_UPDATE_RATE / 3 to get the animation's frame rate.
/* 0x20 */ Vec3s* jointTable; // Current translation of model and rotations of all limbs
/* 0x24 */ Vec3s* morphTable; // Table of values used to morph between animations
/* 0x28 */ f32 morphWeight; // Weight of the current animation morph as a fraction in [0,1]
/* 0x2C */ f32 morphRate; // Reciprocal of the number of frames in the morph
/* 0x30 */ s32 (*update)(); // Can be Loop, Partial loop, Play once, Morph, or Tapered morph. Link only has Loop, Play once, and Morph
/* 0x30 */ s32 (*update)(); // Can be Loop, Partial loop, Play once, Morph, or Tapered morph. Link only has Loop, Play once, and Morph.
/* 0x34 */ s8 initFlags; // Flags used when initializing Link's skeleton
/* 0x35 */ u8 moveFlags; // Flags used for animations that move the actor in worldspace.
/* 0x36 */ s16 prevRot; // Previous rotation in worldspace.
Expand Down
4 changes: 2 additions & 2 deletions soh/include/z64camera.h
Original file line number Diff line number Diff line change
Expand Up @@ -1203,8 +1203,8 @@ typedef struct {
/* 0x14A */ s16 unk_14A;
/* 0x14C */ s16 unk_14C;
/* 0x14E */ s16 childCamIdx;
/* 0x150 */ s16 unk_150;
/* 0x152 */ s16 unk_152;
/* 0x150 */ s16 waterDistortionTimer;
/* 0x152 */ s16 distortionFlags;
/* 0x154 */ s16 prevSetting;
/* 0x156 */ s16 nextCamDataIdx;
/* 0x158 */ s16 nextBGCheckId;
Expand Down
27 changes: 14 additions & 13 deletions soh/include/z64scene.h
Original file line number Diff line number Diff line change
Expand Up @@ -423,20 +423,20 @@ typedef enum {
typedef enum {
/* 0x00 */ SCENE_CMD_ID_SPAWN_LIST,
/* 0x01 */ SCENE_CMD_ID_ACTOR_LIST,
/* 0x02 */ SCENE_CMD_ID_UNUSED_02,
/* 0x03 */ SCENE_CMD_ID_COL_HEADER,
/* 0x02 */ SCENE_CMD_ID_UNUSED_2,
/* 0x03 */ SCENE_CMD_ID_COLLISION_HEADER,
/* 0x04 */ SCENE_CMD_ID_ROOM_LIST,
/* 0x05 */ SCENE_CMD_ID_WIND_SETTINGS,
/* 0x06 */ SCENE_CMD_ID_ENTRANCE_LIST,
/* 0x07 */ SCENE_CMD_ID_SPECIAL_FILES,
/* 0x08 */ SCENE_CMD_ID_ROOM_BEHAVIOR,
/* 0x09 */ SCENE_CMD_ID_UNK_09,
/* 0x0A */ SCENE_CMD_ID_MESH,
/* 0x09 */ SCENE_CMD_ID_UNDEFINED_9,
/* 0x0A */ SCENE_CMD_ID_MESH_HEADER,
/* 0x0B */ SCENE_CMD_ID_OBJECT_LIST,
/* 0x0C */ SCENE_CMD_ID_LIGHT_LIST,
/* 0x0D */ SCENE_CMD_ID_PATH_LIST,
/* 0x0E */ SCENE_CMD_ID_TRANSI_ACTOR_LIST,
/* 0x0F */ SCENE_CMD_ID_ENV_LIGHT_SETTINGS,
/* 0x0E */ SCENE_CMD_ID_TRANSITION_ACTOR_LIST,
/* 0x0F */ SCENE_CMD_ID_LIGHT_SETTINGS_LIST,
/* 0x10 */ SCENE_CMD_ID_TIME_SETTINGS,
/* 0x11 */ SCENE_CMD_ID_SKYBOX_SETTINGS,
/* 0x12 */ SCENE_CMD_ID_SKYBOX_DISABLES,
Expand All @@ -446,7 +446,8 @@ typedef enum {
/* 0x16 */ SCENE_CMD_ID_ECHO_SETTINGS,
/* 0x17 */ SCENE_CMD_ID_CUTSCENE_DATA,
/* 0x18 */ SCENE_CMD_ID_ALTERNATE_HEADER_LIST,
/* 0x19 */ SCENE_CMD_ID_MISC_SETTINGS
/* 0x19 */ SCENE_CMD_ID_MISC_SETTINGS,
/* 0x20 */ SCENE_CMD_ID_MAX
} SceneCommandTypeID;

#define SCENE_CMD_SPAWN_LIST(numSpawns, spawnList) \
Expand All @@ -456,10 +457,10 @@ typedef enum {
{ SCENE_CMD_ID_ACTOR_LIST, numActors, CMD_PTR(actorList) }

#define SCENE_CMD_UNUSED_02(unk, data) \
{ SCENE_CMD_ID_UNUSED_02, unk, CMD_PTR(data) }
{ SCENE_CMD_ID_UNUSED_2, unk, CMD_PTR(data) }

#define SCENE_CMD_COL_HEADER(colHeader) \
{ SCENE_CMD_ID_COL_HEADER, 0, CMD_PTR(colHeader) }
{ SCENE_CMD_ID_COLLISION_HEADER, 0, CMD_PTR(colHeader) }

#define SCENE_CMD_ROOM_LIST(numRooms, roomList) \
{ SCENE_CMD_ID_ROOM_LIST, numRooms, CMD_PTR(roomList) }
Expand All @@ -478,10 +479,10 @@ typedef enum {
curRoomUnk2 | _SHIFTL(showInvisActors, 8, 1) | _SHIFTL(disableWarpSongs, 10, 1) }

#define SCENE_CMD_UNK_09() \
{ SCENE_CMD_ID_UNK_09, 0, CMD_W(0) }
{ SCENE_CMD_ID_UNDEFINED_9, 0, CMD_W(0) }

#define SCENE_CMD_MESH(meshHeader) \
{ SCENE_CMD_ID_MESH, 0, CMD_PTR(meshHeader) }
{ SCENE_CMD_ID_MESH_HEADER, 0, CMD_PTR(meshHeader) }

#define SCENE_CMD_OBJECT_LIST(numObjects, objectList) \
{ SCENE_CMD_ID_OBJECT_LIST, numObjects, CMD_PTR(objectList) }
Expand All @@ -493,10 +494,10 @@ typedef enum {
{ SCENE_CMD_ID_PATH_LIST, 0, CMD_PTR(pathList) }

#define SCENE_CMD_TRANSITION_ACTOR_LIST(numActors, list) \
{ SCENE_CMD_ID_TRANSI_ACTOR_LIST, numActors, CMD_PTR(list) }
{ SCENE_CMD_ID_TRANSITION_ACTOR_LIST, numActors, CMD_PTR(list) }

#define SCENE_CMD_ENV_LIGHT_SETTINGS(numLightSettings, lightSettingsList) \
{ SCENE_CMD_ID_ENV_LIGHT_SETTINGS, numLightSettings, CMD_PTR(lightSettingsList) }
{ SCENE_CMD_ID_LIGHT_SETTINGS_LIST, numLightSettings, CMD_PTR(lightSettingsList) }

#define SCENE_CMD_TIME_SETTINGS(hour, min, speed) \
{ SCENE_CMD_ID_TIME_SETTINGS, 0, CMD_BBBB(hour, min, speed, 0) }
Expand Down
12 changes: 6 additions & 6 deletions soh/soh/Enhancements/savestates.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,8 @@ typedef struct SaveStateInfo {
OnePointCsFull D_8011D8DC_copy[3];
OnePointCsFull D_8011D954_copy[4];
OnePointCsFull D_8011D9F4_copy[3];
int16_t D_8011DB08_copy;
int16_t D_8011DB0C_copy;
int16_t depthPhase_copy;
int16_t screenPlanePhase_copy;
int32_t sOOBTimer_copy;
f32 D_8015CE50_copy;
f32 D_8015CE54_copy;
Expand Down Expand Up @@ -437,8 +437,8 @@ void SaveState::BackupCameraData(void) {
memcpy(info->D_8011D8DC_copy, D_8011D8DC, sizeof(info->D_8011D8DC_copy));
memcpy(info->D_8011D954_copy, D_8011D954, sizeof(info->D_8011D954_copy));
memcpy(info->D_8011D9F4_copy, D_8011D9F4, sizeof(info->D_8011D9F4_copy));
info->D_8011DB08_copy = D_8011DB08;
info->D_8011DB0C_copy = D_8011DB0C;
info->depthPhase_copy = depthPhase;
info->screenPlanePhase_copy = screenPlanePhase;
info->sOOBTimer_copy = sOOBTimer;
info->D_8015CE50_copy = D_8015CE50;
info->D_8015CE54_copy = D_8015CE54;
Expand All @@ -465,8 +465,8 @@ void SaveState::LoadCameraData(void) {
memcpy(D_8011D8DC, info->D_8011D8DC_copy, sizeof(info->D_8011D8DC_copy));
memcpy(D_8011D954, info->D_8011D954_copy, sizeof(info->D_8011D954_copy));
memcpy(D_8011D9F4, info->D_8011D9F4_copy, sizeof(info->D_8011D9F4_copy));
D_8011DB08 = info->D_8011DB08_copy;
D_8011DB0C = info->D_8011DB0C_copy;
depthPhase = info->depthPhase_copy;
screenPlanePhase = info->screenPlanePhase_copy;
sOOBTimer = info->sOOBTimer_copy;
D_8015CE50 = info->D_8015CE50_copy;
D_8015CE54 = info->D_8015CE54_copy;
Expand Down
4 changes: 2 additions & 2 deletions soh/soh/Enhancements/savestates_extern.inc
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ extern "C" OnePointCsFull D_8011D88C[];
extern "C" OnePointCsFull D_8011D8DC[];
extern "C" OnePointCsFull D_8011D954[];
extern "C" OnePointCsFull D_8011D9F4[];
extern "C" int16_t D_8011DB08;
extern "C" int16_t D_8011DB0C;
extern "C" int16_t depthPhase;
extern "C" int16_t screenPlanePhase;
extern "C" int32_t sOOBTimer;
extern "C" f32 D_8015CE50;
extern "C" f32 D_8015CE54;
Expand Down
Loading

0 comments on commit a28d439

Please sign in to comment.