model rendering doc (#1128)

* all over the place * model roundup * missing reset_tiles for jp/ique splat * fix pal * fix ique --------- Co-authored-by: HailSanta <[email protected]>
pmret · Nov 24, 2023 · c2ade57 · c2ade57
1 parent 2b88651
commit c2ade57
Show file tree

Hide file tree

Showing 172 changed files with 1,806 additions and 1,546 deletions.
diff --git a/include/common_structs.h b/include/common_structs.h
@@ -997,8 +997,8 @@ typedef struct TextureHeader {
     /* 0x26 */ u16 mainH;
     /* 0x28 */ u8 isVariant;
     /* 0x29 */ u8 extraTiles; // 0 - none, 1 - mipmap, 2 - ?, 3 - use aux tile
-    /* 0x2A */ u8 colorCombineType : 6;
-    /* 0x2A */ u8 colorCombineSubType : 2;
+    /* 0x2A */ u8 auxCombineType : 6;
+    /* 0x2A */ u8 auxCombineSubType : 2;
     /* 0x2B */ u8 auxFmt : 4;
     /* 0x2B */ u8 mainFmt : 4;
     /* 0x2C */ u8 auxBitDepth : 4;
@@ -1399,9 +1399,9 @@ typedef struct GameStatus {
     /* 0x07B */ char unk_7B;
     /* 0x07C */ b8 healthBarsEnabled;
     /* 0x07D */ b8 keepUsingPartnerOnMapChange;
-    /* 0x07E */ u8 peachFlags; /* (1 = isPeach, 2 = isTransformed, 4 = hasUmbrella) */
-    /* 0x07F */ s8 peachDisguise; /* (1 = koopatrol, 2 = hammer bros, 3 = clubba) */
-    /* 0x080 */ u8 peachBakingIngredient; ///< @see enum PeachBakingItems
+    /* 0x07E */ u8 peachFlags; // see PeachFlags enum
+    /* 0x07F */ s8 peachDisguise; // see PeachDisguises enum
+    /* 0x080 */ u8 peachBakingIngredient; ///< @see PeachBakingItems enum
     /* 0x081 */ b8 multiplayerEnabled;
     /* 0x082 */ Vec2b altViewportOffset;
     /* 0x084 */ s8 playerSpriteSet;

diff --git a/include/effect_shims.h b/include/effect_shims.h
@@ -35,7 +35,7 @@ void shim_draw_box(
 );
 void shim_draw_msg(s32, s32, s32, s32, s32, s32);
 s32 shim_get_msg_width(s32, u16);
-void shim_get_background_color_blend(u8* r, u8* g, u8* b, u8* a);
+void shim_mdl_get_shroud_tint_params(u8* r, u8* g, u8* b, u8* a);
 void shim_sfx_play_sound_at_position(s32 soundID, s32 value2, f32 posX, f32 posY, f32 posZ);
 
 #define guRotateF shim_guRotateF
@@ -68,7 +68,7 @@ void shim_sfx_play_sound_at_position(s32 soundID, s32 value2, f32 posX, f32 posY
 #define draw_box shim_draw_box
 #define draw_msg shim_draw_msg
 #define get_msg_width shim_get_msg_width
-#define get_background_color_blend shim_get_background_color_blend
+#define mdl_get_shroud_tint_params shim_mdl_get_shroud_tint_params
 #define sfx_play_sound_at_position shim_sfx_play_sound_at_position
 
 #endif
diff --git a/include/effects.h b/include/effects.h
@@ -1410,7 +1410,7 @@ typedef struct MerlinHouseStarsFXData {
     /* 0x0C */ f32 unk_0C;
     /* 0x10 */ f32 unk_10;
     /* 0x14 */ f32 unk_14;
-    /* 0x18 */ s32 unk_18;
+    /* 0x18 */ s32 alpha;
     /* 0x1C */ f32 unk_1C;
     /* 0x20 */ f32 unk_20;
     /* 0x24 */ f32 unk_24;

diff --git a/include/enums.h b/include/enums.h
@@ -2487,12 +2487,12 @@ enum LandOnSwitchSubstate {
     LANDING_ON_SWITCH_SUBSTATE_2    = 2,
 };
 
-enum PeachStatusFlags {
-    PEACH_STATUS_FLAG_IS_PEACH          = 0x01,
-    PEACH_STATUS_FLAG_DISGUISED         = 0x02,
-    PEACH_STATUS_FLAG_HAS_PARASOL       = 0x04,
-    PEACH_STATUS_FLAG_8                 = 0x08,
-    PEACH_STATUS_FLAG_DEPRESSED         = 0x10
+enum PeachFlags {
+    PEACH_FLAG_IS_PEACH             = 0x01,
+    PEACH_FLAG_DISGUISED            = 0x02,
+    PEACH_FLAG_HAS_PARASOL          = 0x04,
+    PEACH_FLAG_BLOCK_NEXT_DISGUISE  = 0x08, // next attempt to copy an NPC with parasol will fail
+    PEACH_FLAG_DEPRESSED            = 0x10
 };
 
 enum PeachBakingItems {
@@ -3192,6 +3192,7 @@ enum WindowPriority {
 };
 
 enum RenderModeIndex {
+    // RM1 modes
     RENDER_MODE_IDX_00 = 0x00,
     RENDER_MODE_IDX_01 = 0x01,
     RENDER_MODE_IDX_02 = 0x02,
@@ -3208,6 +3209,7 @@ enum RenderModeIndex {
     RENDER_MODE_IDX_0D = 0x0D,
     RENDER_MODE_IDX_0E = 0x0E,
     RENDER_MODE_IDX_0F = 0x0F,
+    // RM2 modes
     RENDER_MODE_IDX_10 = 0x10,
     RENDER_MODE_IDX_11 = 0x11,
     RENDER_MODE_IDX_12 = 0x12,
@@ -3223,6 +3225,7 @@ enum RenderModeIndex {
     RENDER_MODE_IDX_1C = 0x1C,
     RENDER_MODE_IDX_1D = 0x1D,
     RENDER_MODE_IDX_1E = 0x1E,
+    // RM3 modes
     RENDER_MODE_IDX_1F = 0x1F,
     RENDER_MODE_IDX_20 = 0x20,
     RENDER_MODE_IDX_21 = 0x21,
@@ -3247,6 +3250,7 @@ enum RenderModeIndex {
     RENDER_MODE_IDX_34 = 0x34,
     RENDER_MODE_IDX_35 = 0x35,
     RENDER_MODE_IDX_36 = 0x36,
+    // cloud render modes
     RENDER_MODE_IDX_37 = 0x37,
     RENDER_MODE_IDX_38 = 0x38,
     RENDER_MODE_IDX_39 = 0x39,
@@ -3255,56 +3259,61 @@ enum RenderModeIndex {
     RENDER_MODE_IDX_3C = 0x3C,
 };
 
-/// not really
+// predefined configurations for RDP geometry and render modes
+// though these are called "render modes", they do not strictly correspond to the RDP render modes (as supplied to gDPSetRenderMode)
 enum RenderMode {
-    RENDER_MODE_SURF_SOLID_AA_ZB_LAYER0          = 0x00000000,
-    RENDER_MODE_SURFACE_OPA                      = 0x00000001,
-    RENDER_MODE_02_UNUSED                        = 0x00000002,
-    RENDER_MODE_SURFACE_OPA_NO_AA                = 0x00000003,
-    RENDER_MODE_SURFACE_OPA_NO_ZB                = 0x00000004,
-    RENDER_MODE_DECAL_OPA                        = 0x00000005,
-    RENDER_MODE_06_UNUSED                        = 0x00000006,
-    RENDER_MODE_DECAL_OPA_NO_AA                  = 0x00000007,
-    RENDER_MODE_08_UNUSED                        = 0x00000008,
-    RENDER_MODE_INTERSECTING_OPA                 = 0x00000009,
-    RENDER_MODE_0A_UNUSED                        = 0x0000000A,
-    RENDER_MODE_0B_UNUSED                        = 0x0000000B,
-    RENDER_MODE_0C_UNUSED                        = 0x0000000C,
-    RENDER_MODE_ALPHATEST                        = 0x0000000D,
-    RENDER_MODE_0E_UNUSED                        = 0x0000000E,
-    RENDER_MODE_ALPHATEST_ONESIDED               = 0x0000000F,
-    RENDER_MODE_ALPHATEST_NO_ZB                  = 0x00000010,
-    RENDER_MODE_SURFACE_XLU_LAYER1               = 0x00000011,
-    RENDER_MODE_12_UNUSED                        = 0x00000012,
-    RENDER_MODE_SURFACE_XLU_NO_AA                = 0x00000013,
-    RENDER_MODE_SURFACE_XLU_NO_ZB                = 0x00000014,
-    RENDER_MODE_SURFACE_XLU_ZB_ZUPD              = 0x00000015,
-    RENDER_MODE_SURFACE_XLU_LAYER2               = 0x00000016,
-    RENDER_MODE_17_UNUSED                        = 0x00000017,
-    RENDER_MODE_18_UNUSED                        = 0x00000018,
-    RENDER_MODE_19_UNUSED                        = 0x00000019,
-    RENDER_MODE_DECAL_XLU                        = 0x0000001A,
-    RENDER_MODE_1B_UNUSED                        = 0x0000001B,
-    RENDER_MODE_DECAL_XLU_NO_AA                  = 0x0000001C,
-    RENDER_MODE_1D_UNUSED                        = 0x0000001D,
-    RENDER_MODE_DECAL_XLU_AHEAD                  = 0x0000001E, // special case RENDER_MODE_DECAL_XLU for rendering in front of others
-    RENDER_MODE_1F_UNUSED                        = 0x0000001F,
-    RENDER_MODE_SHADOW                           = 0x00000020,
-    RENDER_MODE_21_UNUSED                        = 0x00000021,
-    RENDER_MODE_SURFACE_XLU_LAYER3               = 0x00000022,
-    RENDER_MODE_23_UNUSED                        = 0x00000023,
-    RENDER_MODE_24_UNUSED                        = 0x00000024,
-    RENDER_MODE_25_UNUSED                        = 0x00000025,
-    RENDER_MODE_INTERSECTING_XLU                 = 0x00000026,
-    RENDER_MODE_27_UNUSED                        = 0x00000027,
-    RENDER_MODE_PASS_THROUGH                     = 0x00000028, // no render mode is set, only geometry modes are initialized
-    RENDER_MODE_SURFACE_XLU_AA_ZB_ZUPD           = 0x00000029,
-    RENDER_MODE_SURFACE_OPA_NO_ZB_BEHIND         = 0x0000002A,
-    RENDER_MODE_ALPHATEST_NO_ZB_BEHIND           = 0x0000002B,
-    RENDER_MODE_SURFACE_XLU_NO_ZB_BEHIND         = 0x0000002C,
-    RENDER_MODE_CLOUD_NO_ZCMP                    = 0x0000002D,
-    RENDER_MODE_CLOUD                            = 0x0000002E,
-    RENDER_MODE_CLOUD_NO_ZB                      = 0x0000002F,
+    // opaque render modes
+    RENDER_MODE_SURF_SOLID_AA_ZB_LAYER0          = 0x00,
+    RENDER_MODE_SURFACE_OPA                      = 0x01,
+    RENDER_MODE_02_UNUSED                        = 0x02,
+    RENDER_MODE_SURFACE_OPA_NO_AA                = 0x03,
+    RENDER_MODE_SURFACE_OPA_NO_ZB                = 0x04,
+    RENDER_MODE_DECAL_OPA                        = 0x05,
+    RENDER_MODE_06_UNUSED                        = 0x06,
+    RENDER_MODE_DECAL_OPA_NO_AA                  = 0x07,
+    RENDER_MODE_08_UNUSED                        = 0x08,
+    RENDER_MODE_INTERSECTING_OPA                 = 0x09,
+    RENDER_MODE_0A_UNUSED                        = 0x0A,
+    RENDER_MODE_0B_UNUSED                        = 0x0B,
+    RENDER_MODE_0C_UNUSED                        = 0x0C,
+    RENDER_MODE_ALPHATEST                        = 0x0D,
+    RENDER_MODE_0E_UNUSED                        = 0x0E,
+    RENDER_MODE_ALPHATEST_ONESIDED               = 0x0F,
+    RENDER_MODE_ALPHATEST_NO_ZB                  = 0x10,
+    RENDER_MODES_LAST_OPAQUE                     = RENDER_MODE_ALPHATEST_NO_ZB,
+    // translucent render modes
+    RENDER_MODE_SURFACE_XLU_LAYER1               = 0x11,
+    RENDER_MODE_12_UNUSED                        = 0x12,
+    RENDER_MODE_SURFACE_XLU_NO_AA                = 0x13,
+    RENDER_MODE_SURFACE_XLU_NO_ZB                = 0x14,
+    RENDER_MODE_SURFACE_XLU_ZB_ZUPD              = 0x15,
+    RENDER_MODE_SURFACE_XLU_LAYER2               = 0x16,
+    RENDER_MODE_17_UNUSED                        = 0x17,
+    RENDER_MODE_18_UNUSED                        = 0x18,
+    RENDER_MODE_19_UNUSED                        = 0x19,
+    RENDER_MODE_DECAL_XLU                        = 0x1A,
+    RENDER_MODE_1B_UNUSED                        = 0x1B,
+    RENDER_MODE_DECAL_XLU_NO_AA                  = 0x1C,
+    RENDER_MODE_1D_UNUSED                        = 0x1D,
+    RENDER_MODE_DECAL_XLU_AHEAD                  = 0x1E, // special case RENDER_MODE_DECAL_XLU for rendering in front of others
+    RENDER_MODE_1F_UNUSED                        = 0x1F,
+    RENDER_MODE_SHADOW                           = 0x20,
+    RENDER_MODE_21_UNUSED                        = 0x21,
+    RENDER_MODE_SURFACE_XLU_LAYER3               = 0x22,
+    RENDER_MODE_23_UNUSED                        = 0x23,
+    RENDER_MODE_24_UNUSED                        = 0x24,
+    RENDER_MODE_25_UNUSED                        = 0x25,
+    RENDER_MODE_INTERSECTING_XLU                 = 0x26,
+    RENDER_MODE_27_UNUSED                        = 0x27,
+    // unusual render modes
+    RENDER_MODE_PASS_THROUGH                     = 0x28, // no render mode is set, only geometry modes are initialized
+    RENDER_MODE_SURFACE_XLU_AA_ZB_ZUPD           = 0x29,
+    RENDER_MODE_SURFACE_OPA_NO_ZB_BEHIND         = 0x2A,
+    RENDER_MODE_ALPHATEST_NO_ZB_BEHIND           = 0x2B,
+    RENDER_MODE_SURFACE_XLU_NO_ZB_BEHIND         = 0x2C,
+    RENDER_MODE_CLOUD_NO_ZCMP                    = 0x2D,
+    RENDER_MODE_CLOUD                            = 0x2E,
+    RENDER_MODE_CLOUD_NO_ZB                      = 0x2F,
 };
 
 enum RenderTaskFlags {
@@ -4304,16 +4313,16 @@ enum GlobalOverrides {
 #define MODEL_FLAGS_MASK_FFF0  (\
       MODEL_FLAG_USES_CUSTOM_GFX \
     | MODEL_FLAG_20 \
-    | MODEL_FLAG_40 \
+    | MODEL_FLAG_IGNORE_FOG \
     | MODEL_FLAG_HAS_LOCAL_VERTEX_COPY \
     | MODEL_FLAG_USE_CAMERA_UNK_MATRIX \
     | MODEL_FLAG_DO_BOUNDS_CULLING \
     | MODEL_FLAG_HAS_TRANSFORM \
     | MODEL_FLAG_HAS_TEX_PANNER \
     | MODEL_FLAG_MATRIX_DIRTY \
     | MODEL_FLAG_IGNORE_MATRIX \
-    | MODEL_FLAG_4000 \
-    | MODEL_FLAG_8000)
+    | MODEL_FLAG_UNUSED_4000 \
+    | MODEL_FLAG_UNUSED_8000)
 
 enum ModelFlags {
     MODEL_FLAG_VALID                    = 0x0001,
@@ -4322,16 +4331,16 @@ enum ModelFlags {
     MODEL_FLAG_TRANSFORM_GROUP_MEMBER   = 0x0008,
     MODEL_FLAG_USES_CUSTOM_GFX          = 0x0010,
     MODEL_FLAG_20                       = 0x0020,
-    MODEL_FLAG_40                       = 0x0040,
+    MODEL_FLAG_IGNORE_FOG               = 0x0040,
     MODEL_FLAG_HAS_LOCAL_VERTEX_COPY    = 0x0080,
     MODEL_FLAG_USE_CAMERA_UNK_MATRIX    = 0x0100,
     MODEL_FLAG_DO_BOUNDS_CULLING        = 0x0200,
     MODEL_FLAG_HAS_TRANSFORM            = 0x0400,
     MODEL_FLAG_HAS_TEX_PANNER           = 0x0800,
     MODEL_FLAG_MATRIX_DIRTY             = 0x1000, // transform matrix changed and combined matrix needs to be recalculated
     MODEL_FLAG_IGNORE_MATRIX            = 0x2000, // set until dirty combined matrix has been recalculated
-    MODEL_FLAG_4000                     = 0x4000,
-    MODEL_FLAG_8000                     = 0x8000,
+    MODEL_FLAG_UNUSED_4000              = 0x4000,
+    MODEL_FLAG_UNUSED_8000              = 0x8000,
 };
 
 enum ModelGroupVisibility {
@@ -4341,6 +4350,20 @@ enum ModelGroupVisibility {
     MODEL_GROUP_OTHERS_VISIBLE  = 3,
 };
 
+enum TintMode {
+    ENV_TINT_UNCHANGED  = -1,
+    // no additional tint is applied (model is still be affected by world fog)
+    ENV_TINT_NONE       = 0,
+    // additional fog which 'shrouds' the world during certain scenes
+    ENV_TINT_SHROUD     = 1,
+    // adds depth-based tint using fog, overriding the world fog for affected models
+    ENV_TINT_DEPTH      = 2,
+    // this mode remaps each color channel range from [0, 255] -> [min, max],
+    // setting a new white point and black point for the scene.
+    // the new max values are stored in PRIMITIVE and the new min values in ENV
+    ENV_TINT_REMAP      = 3,
+};
+
 enum TexPanner {
     //select pan unit
     TEX_PANNER_0    = 0x0,
@@ -5853,14 +5876,6 @@ enum BackgroundFlags {
     BACKGROUND_RENDER_STATE_MASK            = 0xF0,
 };
 
-enum FogModes {
-    FOG_MODE_UNCHANGED = -1,
-    FOG_MODE_0 = 0,
-    FOG_MODE_1 = 1,
-    FOG_MODE_2 = 2,
-    FOG_MODE_3 = 3,
-};
-
 enum EncounterStates {
     ENCOUNTER_STATE_NONE            = 0,
     ENCOUNTER_STATE_CREATE          = 1,

diff --git a/include/functions.h b/include/functions.h
@@ -444,7 +444,7 @@ void set_peach_shadow_scale(Shadow* shadow, f32 scale);
 s32 is_block_on_ground(Entity* block);
 void set_actor_anim(s32 actorID, s32 partID, AnimID animID);
 void set_actor_anim_rate(s32 actorID, s32 partID, f32 rate);
-void set_model_group_visibility(u16, s32, s32);
+void mdl_group_set_visibility(u16, s32, s32);
 void init_enter_world_shared(void);
 s16 update_enter_map_screen_overlay(s16* progress);
 s16 update_exit_map_screen_overlay(s16* progress);
@@ -820,7 +820,7 @@ void set_screen_overlay_center_worldpos(s32 idx, s32 posIdx, s32 x, s32 y, s32 z
 void* mdl_get_next_texture_address(s32);
 s32 cancel_current_message(void);
 void draw_msg(s32 msgID, s32 posX, s32 posY, s32 opacity, s32 palette, u8 style);
-void get_background_color_blend(u8* r, u8* g, u8* b, u8* a);
+void mdl_get_shroud_tint_params(u8* r, u8* g, u8* b, u8* a);
 
 s32 entity_base_block_idle(Entity* entity);
 void add_star_power(s32 amt);
@@ -882,7 +882,7 @@ void btl_cam_use_preset_immediately(s32);
 s32 inflict_status(Actor*, s32, s32);
 s32 try_inflict_status(Actor*, s32, s32);
 s32 inflict_status_set_duration(Actor* actor, s32 statusTypeKey, s32 statusDurationKey, s32 duration);
-void mdl_set_all_fog_mode(s32);
+void mdl_set_all_tint_type(s32);
 void load_model_animator_tree(s32, StaticAnimatorNode**);
 
 s32 inflict_partner_ko(Actor* target, s32 statusTypeKey, s32 duration);
@@ -1014,7 +1014,7 @@ void status_bar_start_blinking_sp_bars(s32 numBarsToBlink);
 void status_bar_draw_number(s32 iconID, s32 x, s32 y, s32 value, s32 numDigits);
 void status_bar_draw_stat(s32 id, s32 x, s32 y, s32, s32);
 void set_background_size(s16, s16, s16, s16);
-void read_background_size(BackgroundHeader*);
+void set_background(BackgroundHeader*);
 void set_max_star_power(s8);
 void sync_status_bar(void);
 void create_cameras_a(void);
@@ -1080,7 +1080,7 @@ void partner_kill_ability_script(void);
 void func_800EF3D4(s32);
 
 void mdl_update_transform_matrices(void);
-void func_8011B950(u16, s32, s32, s32);
+void mdl_group_set_custom_gfx(u16, s32, s32, b32);
 
 void backup_map_collision_data(void);
 void reset_status_bar(void);