Merge pull request #170 from TrainerRiley/finish_poketch_data

Finished documenting PoketchData

include/poketch_data.h

@@ -4,6 +4,11 @@
 #include "pokemon.h"
 #include "savedata.h"
 
+#define POKETCH_MAPMARKER_COUNT 6
+#define POKETCH_POKEMONHISTORY_MAX 12
+#define POKETCH_REGISTRY_SIZE 32
+#define POKETCH_DOTART_SIZE_BYTES 120
+
 /** Poketch app IDs, used to register and switch between apps in the Poketch */
 enum PoketchAppID {
     POKETCH_APPID_DIGITALWATCH = 0,
@@ -29,8 +34,8 @@ enum PoketchAppID {
     POKETCH_APPID_KITCHENTIMER,
     POKETCH_APPID_COLORCHANGER,
     POKETCH_APPID_MATCHUPCHECKER,
-    POKETCH_APPID_STOPWATCH,            // unused
-    POKETCH_APPID_ALARMCLOCK,           // unused
+    POKETCH_APPID_STOPWATCH,    // unused
+    POKETCH_APPID_ALARMCLOCK,   // unused
 
     POKETCH_APPID_MAX
 };
@@ -49,245 +54,149 @@ enum PoketchScreenColor {
     POKETCH_SCREEN_COLOR_MAX,
 };
 
-enum {
-    POKETCH_MAPMARKER_COUNT = 6,
-    POKETCH_REGISTRY_SIZE = 32
-};
 
 /**
  * @brief All of the Poketch's internally tracked data including settings, registered apps, and the data for some apps (eg. pedometer, alarm clock).
  */
 typedef struct PoketchData {
-    u8 unk_00_0 : 1;
-    u8 pedometerEnabled : 1;    //!< Whether or not the pedometer is registered and will take step count updates.
-    u8 unk_00_2 : 1;
-    u8 screenColor : 3;         //!< Screen palette color (see PoketchScreenColor enum above)
-    u8 unk_00_6 : 2;            //!< unused; bitfield padding
+    u8 poketchEnabled : 1;
+    u8 pedometerEnabled : 1;        //!< Whether or not the pedometer is registered and will take step count updates.
+    u8 dotArtModifiedByPlayer : 1;  //!< Whether or not the dot art data has ever been modified by the user. This flag can never be set to FALSE.
+    u8 screenColor : 3;             //!< Screen palette color (see PoketchScreenColor enum above)
+    // u8 padding : 2;
 
     s8 appCount;                                //!< Number of currently registered apps
     s8 appIndex;                                //!< Currently selected app
     u8 appRegistry[POKETCH_REGISTRY_SIZE];      //!< Registration status of all apps. Indices 0-24 correspond to the App IDs in poketch_data.h. Indices 25-31 are unused.
 
-    u32 pedometer;         //!< Step counter
+    u32 stepCount;
 
-    u16 alarmSet : 1;      //!< Whether or not the alarm is currently enabled.
-    u16 alarmHour : 5;     //!< Current Hour setting on the alarm clock.
-    u16 alarmMinute : 6;   //!< Current Minute setting on the alarm clock.
-    u16 unk_28_12 : 4;     //!< unused; bitfield padding
+    u16 alarmSet : 1;
+    u16 alarmHour : 5;
+    u16 alarmMinute : 6;
+    // u16 padding : 4;
 
-    u8 unk_2A[120];
+    u8 dotArtData[POKETCH_DOTART_SIZE_BYTES];   //!< All pixel information for the Dot Art app
 
     u32 calendarMarkBitmap;     //!< Bitmap for every day in the calendar month and whether it's been marked
-    u8 calendarMonth;      //!< Current calendar month
+    u8 calendarMonth;
 
     /**
     * @brief XY coordinates of a single Map Marker in the Marking Map app
     */
     struct {
-        u8 x;                                       //!< X coordinate of map marker
-        u8 y;                                       //!< Y coordinate of map marker
-    } markMapPositions[POKETCH_MAPMARKER_COUNT];    //!< Map markers
+        u8 x;
+        u8 y;
+    } markMapPositions[POKETCH_MAPMARKER_COUNT];
 
+    /**
+    * @brief Relevant data for Pokemon History app
+    */
     struct {
-        u16 unk_00;
-        u16 unk_02;
-        u32 unk_04;
-    } unk_B8[12];
+        u16 species;
+        u16 icon;
+        u32 form;
+    } pokemonHistoryQueue[POKETCH_POKEMONHISTORY_MAX];   //!< The pokemon to display in the Pokemon History app
 } PoketchData;
 
-/**
- * Returns the size of the PoketchData object.
- *
- * @return the size of the PoketchData object.
- */
 int Poketch_SaveSize(void);
 
-/**
- * Initializes the given PoketchData object.
- *
- * @param poketchData:      The PoketchData to initialize.
- */
 void Poketch_Init(PoketchData *poketchData);
 
-void sub_020567D0(PoketchData *poketchData);
-BOOL sub_020567E0(PoketchData *poketchData);
+void PoketchData_Enable(PoketchData *poketchData);
 
-/**
- * Checks whether or not the given AppID is already registered in the Poketch.
- * Valid apps are in the range 0-24.
- *
- * @param poketchData:      The Poketch data to check.
- * @param appID:            The App ID to check for.
- *
- * @return TRUE if the app is registered, FALSE if not.
- */
-BOOL PoketchData_CheckAppRegistered(PoketchData *poketchData, enum PoketchAppID appID);
+BOOL PoketchData_IsEnabled(PoketchData *poketchData);
+
+BOOL PoketchData_IsAppRegistered(PoketchData *poketchData, enum PoketchAppID appID);
 
-/**
- * Registers the app with the given ID, making it accessible to the player.
- *
- * @param poketchData:      The Poketch data to check.
- * @param appID:            The ID of the app to register. This function asserts that the value is in the range [0, POKETCH_APPID_MAX).
- *
- * @return TRUE if the was successfully registered, FALSE if it was already registered.
- */
 BOOL PoketchData_RegisterApp(PoketchData *poketchData, enum PoketchAppID appID);
 
-/**
- * Gets the currently active Poketch app.
- *
- * @param poketchData:      The Poketch data to check.
- *
- * @return The ID of the current app.
- */
 enum PoketchAppID PoketchData_CurrentAppID(const PoketchData *poketchData);
 
 /**
  * Sets the current Poketch app to the next registered app, skipping unregistered App IDs and wrapping around if necessary.
- *
- * @param poketchData:      The Poketch data to update.
- *
- * @return The new current app ID.
  */
 int PoketchData_IncrementAppID(PoketchData *poketchData);
 
 /**
  * Sets the current Poketch app to the previous registered app, skipping unregistered App IDs and wrapping around if necessary.
- *
- * @param poketchData:      The Poketch data to update.
- *
- * @return The new current app ID.
  */
 int PoketchData_DecrementAppID(PoketchData *poketchData);
 
-/**
- * Gets the current Poketch's color setting.
- *
- * @param poketchData:      The Poketch data to check.
- *
- * @return The Poketch's color setting.
- */
 u32 PoketchData_CurrentScreenColor(const PoketchData *poketchData);
 
 /**
- * Sets the Poketch's color setting.
- *
- * @param poketchData:      The Poketch data to update. This function assert checks this pointer.
- * @param screenColor:      The color to set (see PoketchScreenColor enum above). This function asserts that the value is less than POKETCH_SCREEN_COLOR_MAX.
+ * Sets the Poketch's color setting with values from the PoketchScreenColor enum above.
+ * This function asserts that the given value is less than POKETCH_SCREEN_COLOR_MAX.
  */
 void PoketchData_SetScreenColor(PoketchData *poketchData, u32 screenColor);
 
-/**
- * Gets the Pedometer's current step count value.
- *
- * @param poketchData:      The Poketch data to check.
- *
- * @return pedometer's step count.
- */
-u32  PoketchData_PedometerValue(const PoketchData *poketchData);
+u32 PoketchData_StepCount(const PoketchData *poketchData);
 
 /**
- * Sets the Poketch's pedometer value.
- *
- * @param poketchData:      The Poketch data to update.
- * @param value:            The step value to set.
+ * Overwrites the current step count. This function will not do anything unless the Pedometer app is registered.
  */
-void PoketchData_SetPedometerValue(PoketchData *poketchData, u32 value);
+void PoketchData_SetStepCount(PoketchData *poketchData, u32 value);
 
-/**
- * Returns whether or not the Poketch Alarm Clock app's alarm is set.
- *
- * @param poketchData:      The Poketch data to check.
- *
- * @return TRUE if the alarm is currently set, FALSE if not.
- */
 BOOL PoketchData_IsAlarmSet(const PoketchData *poketchData);
 
-/**
- * Gets the currently stored time on the Alarm Clock app.
- *
- * @param poketchData:      The Poketch data to check.
- * @param hour:             Where the currently set hour value will be stored.
- * @param minute:           Where the currently set minute value will be stored.
- */
 void PoketchData_AlarmTime(const PoketchData *poketchData, u32 *hour, u32 *minute);
 
-/**
- * Configures all the Alarm Clock settings, including whether the alarm is set.
- *
- * @param poketchData:      The Poketch data to update.
- * @param enabled:          Whether the alarm is set. TRUE means the alarm will go off at the given hour and minute.
- * @param hour:             The hour value of the alarm clock.
- * @param minute:           The minute value of the alarm clock.
- */
 void PoketchData_SetAlarm(PoketchData *poketchData, BOOL enabled, u32 hour, u32 minute);
 
 /**
- * Marks the given date on the Calendar app as highlighted.
- *
- * @param poketchData:      The Poketch data to update.
- * @param month:            The month of the date to mark. If this month does not match the currently stored month, 
- *                          the month will update to this value and clear all marks on the calendar (except the one on the passed in day).
- * @param day:              The day of the date to mark.
+ * Marks the given date on the Calendar app as highlighted. 
+ * Passing this function a new month will change the month on the calendar and clear all days except the given one.
  */
 void PoketchData_SetCalendarMark(PoketchData *poketchData, u32 month, u32 day);
 
 /**
  * Clears the mark on the given date on the Calendar app.
- *
- * @param poketchData:      The Poketch data to update.
- * @param month:            The month of the date to clear. If this month does not match the currently stored month, 
- *                          the month will update to this value and clear all marks on the calendar.
- * @param day:              The day of the date to clear.
+ * Passing this function a new month will change the month on the calendar and clear every day.
  */
 void PoketchData_ClearCalendarMark(PoketchData *poketchData, u32 month, u32 day);
 
-/**
- * Checks whether the given date is currently marked on the calendar.
- *
- * @param poketchData:      The Poketch data to check.
- * @param month:            The month of the date to check.
- * @param day:              The day of the date to check.
- * 
- * @param return TRUE if the date is marked, FALSE if not. If the given month is not the currently stored month, returns FALSE.
- */
 BOOL PoketchData_CalendarMarked(const PoketchData *poketchData, u32 month, u32 day);
 
 /**
- * Sets the location of a map marker.
- *
- * @param poketchData:      The Poketch data to update.
- * @param index:            The Map Marker to set. This function asserts that the index is less than POKETCH_MAPMARKER_COUNT.
- * @param x:                The x coordinate for the map marker.
- * @param y:                The y coordinate for the map marker.
+ * Sets the location of a map marker. Asserts that index is less than POKETCH_MAPMARKER_COUNT.
  */
 void PoketchData_SetMapMarker(PoketchData *poketchData, int index, u8 x, u8 y);
 
 /**
- * Gets the location of a map marker.
- *
- * @param poketchData:      The Poketch data to update.
- * @param index:            The Map Marker to check. This function asserts that the index is less than POKETCH_MAPMARKER_COUNT.
- * @param x:                The int where the x coordinate will be stored.
- * @param y:                The int where the y coordinate will be stored.
+ * Gets the location of a map marker. Asserts that index is less than POKETCH_MAPMARKER_COUNT.
  */
 void PoketchData_MapMarkerPos(const PoketchData *poketchData, int index, u8 *x, u8 *y);
 
-BOOL sub_02056A10(const PoketchData *poketchData);
-void sub_02056A18(const PoketchData *poketchData, u8 *param1);
-void sub_02056A2C(PoketchData *poketchData, const u8 *param1);
-void sub_02056A48(PoketchData *poketchData, const BoxPokemon *param1);
-int sub_02056AAC(const PoketchData *poketchData);
-void sub_02056AC8(const PoketchData *poketchData, int param1, int *param2, int *param3);
-u32 sub_02056AFC(const PoketchData *poketchData, int param1);
+/**
+ * Checks whether or not the Dot Art data has been modified at any point. 
+ * This will return FALSE until PoketchData_ModifyDotArtData is called, at which point it will always return TRUE.
+ */
+BOOL PoketchData_DotArtModified(const PoketchData *poketchData);
+
+void PoketchData_CopyDotArtData(const PoketchData *poketchData, u8 *dst);
+
+void PoketchData_ModifyDotArtData(PoketchData *poketchData, const u8 *src);
+
+/**
+ * Adds a new Pokemon to the end of the Pokemon History list.
+ */
+void PoketchData_PokemonHistoryEnqueue(PoketchData *poketchData, const BoxPokemon *boxPokemon);
+
+int PoketchData_PokemonHistorySize(const PoketchData *poketchData);
 
 /**
- * Retrieves the PoketchData from the given SaveData.
- *
- * @param SaveData:         The SaveData to read from.
- *
- * @return The PoketchData.
+ * Gets the species and icon info of a given index in the Pokemon History.
+ * This function asserts that index is less than POKETCH_POKEMONHISTORY_MAX.
  */
+void PoketchData_PokemonHistorySpeciesAndIcon(const PoketchData *poketchData, int index, int *species, int *icon);
+
+/**
+ * Gets the form info of a given index in the pokemon history.
+ * This function asserts that index is less than POKETCH_POKEMONHISTORY_MAX.
+ */
+u32 PoketchData_PokemonHistoryForm(const PoketchData *poketchData, int index);
+
 PoketchData* SaveData_PoketchData(SaveData *saveData);
 
 #endif // POKEPLATINUM_POKETCH_DATA_H

src/overlay005/ov5_021DDAE4.c

@@ -45,7 +45,7 @@ static BOOL ov5_021DDAE4 (UnkStruct_020508D4 * param0)
 
             Overlay_UnloadByID(FS_OVERLAY_ID(overlay24));
             Overlay_LoadByID(FS_OVERLAY_ID(overlay25), 2);
-            sub_020567D0(v2);
+            PoketchData_Enable(v2);
             ov25_02253CE8(v0, &v0->unk_04->unk_14, v0->unk_0C, v0->unk_08, sub_0200A914(1));
             v1->unk_00++;
         }

src/overlay005/ov5_021EA714.c

@@ -31,7 +31,7 @@ void ov5_021EA728 (UnkStruct_0203CDB0 * param0)
     PoketchData * v0 = SaveData_PoketchData(param0->unk_0C);
     UnkStruct_020507E4 * v1 = SaveData_Events(param0->unk_0C);
 
-    if (sub_020567E0(v0)
+    if (PoketchData_IsEnabled(v0)
         && (sub_0206AE2C(v1) == 0)) {
         Overlay_LoadByID(FS_OVERLAY_ID(overlay25), 2);
         ov25_02253CE8(param0, &param0->unk_04->unk_14, param0->unk_0C, param0->unk_08, sub_0200A914(1));
@@ -46,7 +46,7 @@ void ov5_021EA790 (UnkStruct_0203CDB0 * param0)
     PoketchData * v0 = SaveData_PoketchData(param0->unk_0C);
     UnkStruct_020507E4 * v1 = SaveData_Events(param0->unk_0C);
 
-    if (sub_020567E0(v0)
+    if (PoketchData_IsEnabled(v0)
         && (sub_0206AE2C(v1) == 0)) {
         ov25_02253D5C(param0->unk_04->unk_14);
     } else {
@@ -59,7 +59,7 @@ u8 ov5_021EA7CC (UnkStruct_0203CDB0 * param0)
     PoketchData * v0 = SaveData_PoketchData(param0->unk_0C);
     UnkStruct_020507E4 * v1 = SaveData_Events(param0->unk_0C);
 
-    if (sub_020567E0(v0)
+    if (PoketchData_IsEnabled(v0)
         && (sub_0206AE2C(v1) == 0)) {
         if (ov25_02253D70(param0->unk_04->unk_14)) {
             param0->unk_04->unk_14 = NULL;

src/overlay016/ov16_0223DF00.c

@@ -1124,7 +1124,7 @@ void ov16_0223EF2C (BattleSystem * param0, int param1, int param2)
 void ov16_0223EF48 (BattleSystem * param0, Pokemon * param1)
 {
     if (param0->unk_98) {
-        sub_02056A48(param0->unk_98, Pokemon_GetBoxPokemon(param1));
+        PoketchData_PokemonHistoryEnqueue(param0->unk_98, Pokemon_GetBoxPokemon(param1));
     }
 }
 

src/overlay025/ov25_02253CE0.c

@@ -216,13 +216,13 @@ void ov25_02253D7C (UnkStruct_ov25_02253CE0 * param0, int param1, u32 param2)
         break;
     case 5:
     {
-        u32 v0 = PoketchData_PedometerValue(param0->unk_58);
+        u32 v0 = PoketchData_StepCount(param0->unk_58);
 
         if (++v0 > 99999) {
             v0 = 0;
         }
 
-        PoketchData_SetPedometerValue(param0->unk_58, v0);
+        PoketchData_SetStepCount(param0->unk_58, v0);
         param0->unk_07 = 1;
     }
     break;