Format and document utility files (#246)

* Format and document utility files

* Add Doxyfile

* small updates for cleanup

* Final touches for util docs

* Replace `_` with `s_` for static functions

* update for clang-format changes

* Update include/audio_utils.h

Co-authored-by: MeirGavish <meir.gavish@gmail.com>

* Apply suggestions from code review

Co-authored-by: MeirGavish <meir.gavish@gmail.com>

* Update include/audio_utils.h

Co-authored-by: MeirGavish <meir.gavish@gmail.com>

* Update include/graphic_utils.h

Co-authored-by: MeirGavish <meir.gavish@gmail.com>

* Make clang-format happy :)

* Update gitignore for doxygen

* restor graphic_utils.c to main

* update graphics utils

* tmp

* tmp

* get it to compile

* fix some bad merge mistakes

* Fix clang format

* Apply suggestions from code review

Co-authored-by: MeirGavish <meir.gavish@gmail.com>

* make clang-format happy

---------

Co-authored-by: MeirGavish <meir.gavish@gmail.com>

.github/workflows/clang_format_ci_workflow.yml

@@ -18,8 +18,12 @@ jobs:
 
       - name: Run clang-format
         run: >
-          clang-format --dry-run -Werror
+          clang-format --dry-run -Werror 
-          include/bitset.h source/bitset.c
+          include/bitset.h source/bitset.c 
+          include/affine_background.h source/affine_background.c 
+          include/audio_utils.h source/audio_utils.c 
+          include/graphic_utils.h source/graphic_utils.c 
+          include/util.h source/util.c
           include/pool.h source/pool.c
           include/card.h source/card.c 
           include/game.h source/game.c 

.gitignore

@@ -1,11 +1,12 @@
-/.vscode
+/.vscode
-/build
+/build
-/.vs
+/.vs
-*.sln
+*.sln
-*.vcxproj*
+*.vcxproj*
-/balatro-gba/x64/**
+/balatro-gba/x64/**
-/tests/bitset/build
+/tests/bitset/build
-/tests/list/build
+/tests/list/build
-/tests/pool/build
+/tests/pool/build
-tests/util/.vscode
+doc
-tests/util/build
+tests/util/.vscode
+tests/util/build

include/affine_background.h

@@ -1,26 +1,93 @@
+/**
+ * @file affine_background.h
+ *
+ * @brief Utilities for affine background on GBA
+ */
 #ifndef AFFINE_BACKGROUND_H
 #define AFFINE_BACKGROUND_H
 
-#include <tonc.h>
-
 #include "graphic_utils.h"
 
-#define AFFINE_BG_IDX 2 // The index of the affine background BGCNT register etc.
+#include <tonc.h>
-#define AFFINE_BG_PAL_LEN 16
-#define AFFINE_BG_PB (PAL_ROW_LEN * 10) // This isn't really a palette bank, just the starting index of the palette
 
+/**
+ * @def AFFINE_BG_IDX
+ * @brief The index of the affine background BGCNT register etc.
+ */
+#define AFFINE_BG_IDX 2
+
+/**
+ * @def AFFINE_BG_PAL_LEN
+ * @brief Number of u16 colors available in the palate.
+ */
+#define AFFINE_BG_PAL_LEN 16
+
+/**
+ * @def AFFINE_BG_PB
+ * @brief The starting index of the background palette.
+ */
+#define AFFINE_BG_PB (PAL_ROW_LEN * 10)
+
+/**
+ * @brief An ID to specify background rendering types.
+ */
 enum AffineBackgroundID
 {
+    /**
+     * @brief Display background for main menu.
+     *
+     * Signifies which background to use and provides a higher quality affine
+     * mode to display when there is no game logic.
+     */
     AFFINE_BG_MAIN_MENU,
+    /**
+     * @brief Display background for game play.
+     *
+     * Signifies which background to use and provides a lower quality affine
+     * mode to keep resources down during play.
+     */
     AFFINE_BG_GAME,
 };
 
+/**
+ * @brief Initialize resources for affine background rendering
+ */
 void affine_background_init();
+
+/**
+ * @brief Interrupt routine to update display on HBLANK
+ */
 IWRAM_CODE void affine_background_hblank();
+
+/**
+ * @brief Per-frame update of the affine background
+ */
 IWRAM_CODE void affine_background_update();
+
+/**
+ * @brief Update the affine background color
+ *
+ * @param color @ref COLOR to set
+ */
 void affine_background_set_color(COLOR color);
-// Must be called with an array of size at least  AFFINE_BG_PAL_LEN
+
-void affine_background_load_palette(const u16 *src);
+/**
+ * @brief Set the background palette
+ *
+ * Must be called with an array of size at least @ref AFFINE_BG_PAL_LEN
+ *
+ * @param src pointer to palette to set
+ */
+void affine_background_load_palette(const u16* src);
+
+/**
+ * @brief Update the background id
+ *
+ * Update the background id by configuring display registers and loading
+ * the image and palette used for the specified id.
+ *
+ * @param new_bg @ref AffineBackgrounID to set
+ */
 void affine_background_change_background(enum AffineBackgroundID new_bg);
 
 #endif // AFFINE_BACKGROUND_H

include/audio_utils.h

@@ -1,16 +1,51 @@
-#ifndef AUDIO_UTILS_H
+/**
-#define AUDIO_UTILS_H
+ * @file audio_utils.h
-
+ *
-#include <mm_types.h>
+ * @brief Utilities for using maxmod to play sound effects
-
+ */
-#define MM_FULL_VOLUME      255
+#ifndef AUDIO_UTILS_H
-#define MM_PAN_CENTER       128
+#define AUDIO_UTILS_H
-#define MM_BASE_PITCH_RATE  1024
+
-
+#include <mm_types.h>
-#define SFX_DEFAULT_VOLUME  MM_FULL_VOLUME
+
-#define SFX_DEFAULT_PAN     MM_PAN_CENTER
+/**
-#define SFX_DEFAULT_HANDLE  0
+ * @def MM_FULL_VOLUME
-
+ * @brief The maximum volume for maxmod mm_sound_effect.volume
-void play_sfx(mm_word id, mm_word rate);
+ */
-
+#define MM_FULL_VOLUME 255
-#endif
+
+/**
+ * @def MM_PAN_CENTER
+ * @brief The center pan of stereo audio for maxmod
+ */
+#define MM_PAN_CENTER 128
+
+/**
+ * @def MM_BASE_PITCH_RATE
+ * @brief The default pitch rate for the sound effect played.
+ *
+ * Increasing the rate increases the pitch, while decreasing lowers the pitch.
+ */
+#define MM_BASE_PITCH_RATE 1024
+
+/**
+ * @def SFX_DEFAULT_VOLUME
+ * @brief Default volume for sound effects
+ */
+#define SFX_DEFAULT_VOLUME MM_FULL_VOLUME
+
+/**
+ * @def SFX_DEFAULT_PAN
+ * @brief The default stereo pan, will always be center pan.
+ */
+#define SFX_DEFAULT_PAN MM_PAN_CENTER
+
+/**
+ * @brief Play a sound effect, wrapper for mmEffectEx()
+ *
+ * @param id the sound id to play, from maxmod compiled soundbank.h header
+ * @param rate the pitch rate, the default value is @ref MM_BASE_PTCH_RATE
+ */
+void play_sfx(mm_word id, mm_word rate);
+
+#endif

include/bitset.h

@@ -1,6 +1,7 @@
-/** @file bitset.h
+/**
+ * @file bitset.h
  *
- *  @brief A bitset for operating on flags
+ * @brief A bitset for operating on flags
  */
 #ifndef BITSET_H
 #define BITSET_H

include/graphic_utils.h

@@ -1,55 +1,140 @@
-#ifndef GRAPHIC_UTILS_H
+/**
-#define GRAPHIC_UTILS_H
+ * @file graphic_utils.h
-
+ *
-#include <tonc_video.h>
+ * @brief Graphic utility functions
-
+ *
-/* This file contains general utils and wrappers that relate to 
+ * This file contains general utils and wrappers that relate to
  * graphics/video/vram and generally displaying things on the screen.
  * Mostly wrappers and defines for using tonc.
- * 
+ *
- * Note: the code here assumes we're working with a single screenblock 
+ * Note: the code here assumes we're working with a single screenblock
- * which should be true for this entire game since a screenblock 
+ * which should be true for this entire game since a screenblock
  * is enough to contain a full screen (and more)
  * and there isn't any scrolling etc.
  */
+#ifndef GRAPHIC_UTILS_H
+#define GRAPHIC_UTILS_H
 
-/* Reminder:
+#include <tonc_math.h>
+#include <tonc_video.h>
+
+/**
+ * @name Graphics Utilities Constants
+ *
+ * Reminder:
  *  Screen Base Block is the base for the screenblock entries i.e. tilemap
  *  Character Base Block is the base for the tiles themselves
+ *
+ * @{
  */
-#define MAIN_BG_SBB 31 
+
+/** @def MAIN_BG_SBB */
+#define MAIN_BG_SBB 31
+
+/** @def MAIN_BG_CBB */
 #define MAIN_BG_CBB 1
+
+/** @def TTE_SBB */
 #define TTE_SBB 30
+
+/** @def MAIN_BG_SBB */
 #define TTE_CBB 0
+
+/** @def AFFINE_BG_SBB */
 #define AFFINE_BG_SBB 2
+
+/** @def AFFINE_BG_CBB */
 #define AFFINE_BG_CBB 2
+
+/** @def PAL_ROW_LEN */
 #define PAL_ROW_LEN 16
+
+/** @def NUM_PALETTES */
 #define NUM_PALETTES 16
 
+/**
+ * @def TILE_SIZE
+ * @brief Tile size in pixels, both height and width as tiles are square
+ */
+#define TILE_SIZE 8
+
+/** @} */
+
+/**
+ * @name TTE Palette constants
+ *
+ * @{
+ */
+
+/** @def TTE_BIT_UNPACK_OFFSET */
 #define TTE_BIT_UNPACK_OFFSET 14
+
+/** @def TTE_BIT_ON_CLR_IDX */
 #define TTE_BIT_ON_CLR_IDX TTE_BIT_UNPACK_OFFSET + 1
 
-#define TTE_YELLOW_PB   12  // 0xC
+/** @def TTE_YELLOW_PB */
-#define TTE_BLUE_PB     13  // 0xD
+#define TTE_YELLOW_PB 12 // 0xC
-#define TTE_RED_PB      14  // 0xE
-#define TTE_WHITE_PB    15  // 0xF
-#define TTE_SPECIAL_PB_MULT_OFFSET 0x1000 //TODO: Change to a better name?
 
-#define TEXT_CLR_YELLOW RGB15(31, 20, 0)    // 0x029F
+/** @def TTE_BLUE_PB */
-#define TEXT_CLR_BLUE   RGB15(0, 18, 31)    // 0x7E40
+#define TTE_BLUE_PB 13 // 0xD
-#define TEXT_CLR_RED    RGB15(31, 9, 8)     // 0x213F
-#define TEXT_CLR_WHITE  CLR_WHITE
 
-/* Dimensions for a screenblock.
+/** @def TTE_RED_PB */
+#define TTE_RED_PB 14 // 0xE
+
+/** @def TTE_WHITE_PB */
+#define TTE_WHITE_PB 15 // 0xF
+
+/** @def TTE_SPECIAL_PB_MULT_OFFSET */
+#define TTE_SPECIAL_PB_MULT_OFFSET 0x1000
+
+/**
+ * @def TTE_CHAR_SIZE
+ *
+ * @brief By default TTE characters occupy a single tile
+ */
+#define TTE_CHAR_SIZE TILE_SIZE
+
+/** @} */
+
+/**
+ * @name Text colors
+ *
+ * @{
+ */
+
+/** @def TEXT_CLR_YELLOW */
+#define TEXT_CLR_YELLOW RGB15(31, 20, 0) // 0x029F
+
+/** @def TEXT_CLR_BLUE */
+#define TEXT_CLR_BLUE RGB15(0, 18, 31) // 0x7E40
+
+/** @def TEXT_CLR_RED */
+#define TEXT_CLR_RED RGB15(31, 9, 8) // 0x213F
+
+/** @def TEXT_CLR_WHITE */
+#define TEXT_CLR_WHITE CLR_WHITE
+
+/** @} */
+
+/**
+ * @name Dimensions for a screenblock.
+ *
  * A 1024 size screenblock is arranged in a grid of 32x32 screen entries
  * Interestingly since each block is 8x8 pixels, the 240x160 GBA screen
  * is smaller than the screenblock, only the top left part of the screenblock
  * is displayed on the screen.
+ *
+ * @{
  */
+
+/** @def SE_ROW_LEN */
 #define SE_ROW_LEN 32
+
+/** @def SE_COL_LEN */
 #define SE_COL_LEN 32
 
-// Since y direction goes from the top of the screen to the bottom
+/** @} */
+
 enum ScreenVertDir
 {
     SCREEN_UP = -1,
@@ -68,104 +153,146 @@ enum OverflowDir
     OVERFLOW_RIGHT = SCREEN_RIGHT
 };
 
-// Tile size in pixels, both height and width as tiles are square
+/** @} */
-#define TILE_SIZE 8
-#define EFFECT_TEXT_SEPARATION_AMOUNT 32; // If we need to show multiple effects at once
-
-// By default TTE characters occupy a single tile
-#define TTE_CHAR_SIZE TILE_SIZE
 
 // When making this, missed that it already exists in tonc_math.h
 typedef RECT Rect;
 
-/* Gets the screenblock entry for the given coordinates (x, y).
+/**
- * x and y are in number of tiles.
+ * @brief Get the width of a rectangle
- * Returns the screenblock entry.
+ *
+ * @param rect a @ref Rect to measure
+ *
+ * @return The width of the rectangle.
  */
-SE main_bg_se_get_se(BG_POINT pos);
-
 INLINE int rect_width(const Rect* rect)
 {
     return max(0, rect->right - rect->left + 1);
 }
 
+/**
+ * @brief Get the height of a rectangle
+ *
+ * @param rect a @ref Rect to measure
+ *
+ * @return The height of the rectangle, or 0 if rect->right < rect->left
+ */
 INLINE int rect_height(const Rect* rect)
 {
     return max(0, rect->bottom - rect->top + 1);
 }
 
-/* Copies an SE rect vertically in direction by a single tile.
+/**
+ * @brief Copies an SE rect vertically in direction by a single tile.
+ *
  * bg_sbb is the SBB of the background in which to move the rect
  * se_rect dimensions are in number of tiles.
- * 
+ *
  * NOTE: This does not work with TTE_SBB, probably because it's 4BPP...
+ *
+ * If you are doing this operation you are probably doing this in the main
+ * background and you should use main_bg_se_copy_rect_1_tile_vert() instead.
+ *
+ * @param bg_sbb the SBB of the background in which to move the rect.
+ *
+ * @param se_rect dimensions are in number of tiles.
+ *
+ * @param direction must be either @ref SE_UP or @ref SE_DOWN.
  */
 void bg_se_copy_rect_1_tile_vert(u16 bg_sbb, Rect se_rect, enum ScreenVertDir direction);
 
-/* Clears a rect in the main background.
+/**
- * The se_rect dimensions need to be in number of tiles.
+ * @brief Clears a rect in the main background.
+ *
+ * @param se_rect dimensions need to be in number of tiles.
  */
 void main_bg_se_clear_rect(Rect se_rect);
 
-/* Copies a rect in the main background vertically in direction by a single tile.
+/**
- * se_rect dimensions are in number of tiles.
+ * @brief Copies a rect in the main background vertically in direction by a single tile.
+ *
+ * @param se_rect dimensions are in number of tiles.
+ *
+ * @param direction must be either @ref SE_UP or @ref SE_DOWN.
  */
 void main_bg_se_copy_rect_1_tile_vert(Rect se_rect, enum ScreenVertDir direction);
 
-/* Copies a rect in the main background from se_rect to the position (x, y).
+/**
- * se_rect dimensions are in number of tiles.
+ * @brief Copies a rect in the main background from se_rect to the position (x, y).
- * x and y are the coordinates in number of tiles.
+ *
+ * @param se_rect dimensions are in number of tiles.
+ *
+ * @param dest_pos x and y are the coordinates in number of tiles.
  */
 void main_bg_se_copy_rect(Rect se_rect, BG_POINT dest_pos);
 
-/* Copies a screen entry to a rect in the main background.
+/**
- * se_rect dimensions are in number of tiles.
+ * @brief Copies a 3x3 rect and expands it to a passed size.
- * The tile is copied to the top left corner of the rect.
+ *
- */
+ * Performs the following operation:
-void main_bg_se_fill_rect_with_se(SE tile, Rect se_rect);
+ *
-
+ * 1. The 3x3 rect is stretched to fill se_rect_dest.
-/* Copies a 3x3 rect into se_rect_dest, the 3x3 rect is stretched to fill se_rect_dest. 
+ * 2. The corners are copied
- * The corners are copied, the sides are stretched, and the center is filled.
+ * 3. The sides are stretched
- * The parameter se_rect_src_3x3_top_left points to the top left corner of the source
+ * 4. The center is filled.
- * 3x3 rect.
+ *
- * Dest rect sides can be of length 2, then the sides are not copied, only the corners.
+ * @param se_rect_dest destination for 3x3 copy, if rect sides are length 2, then the sides are not
- * But dest rect sides must be at least 2.
+ * copied, only the corners. **But dest rect sides must be at least 2.**
+ *
+ * @param se_rect_src_3x3_top_left points to the top left corner of the source 3x3 rect.
  */
 void main_bg_se_copy_expand_3x3_rect(Rect se_rect_dest, BG_POINT se_rect_src_3x3_top_left);
 
-/* Moves a rect in the main background vertically in direction by a single tile.
+/**
+ * @brief Moves a rect in the main background vertically in direction by a single tile.
+ *
  * Note that tiles in the previous location will be transparent (0x000)
  * so maybe copy would be a better choice if you don't want to delete things
- * se_rect dimensions are in number of tiles.
+ *
+ * @param se_rect dimensions are in number of tiles.
+ * @param direction must be either @ref SE_UP or @ref SE_DOWN.
  */
 void main_bg_se_move_rect_1_tile_vert(Rect se_rect, enum ScreenVertDir direction);
 
-// A wrapper for tte_erase_rect that would use the rect struct
+/**
+ * @brief A wrapper for tte_erase_rect that would use the rect struct
+ *
+ * @param rect rectangle to erase
+ */
 void tte_erase_rect_wrapper(Rect rect);
 
-/* Changes rect->left so it fits a string exactly when right aligned to rect->right.
+/**
- * 
+ * @brief Changes rect->left so it fits the digits of num exactly when right aligned to rect->right.
- * overflow_direction determines the direction the string will overflow
+ * Assumes num is not negative.
+ *
+ * overflow_direction determines the direction the number will overflow
  * if it's too large to fit inside the rect.
- * 
+ *
- * The rect is in number of pixels but should be a multiple of TTE_CHAR_SIZE
- * so it's a whole number of tiles to fit TTE characters
- * 
  * Note that both rect->left and rect-right need to be defined, top and bottom don't matter
+ *
+ * @param rect is in number of pixels but should be a multiple of TILE_SIZE, so it's a whole number
+ * of tiles to fit TTE characters
+ *
+ * @param num number to display
+ *
+ * @param overflow_direction either OVERFLOW_LEFT or OVERFLOW_RIGHT.
  */
-void update_text_rect_to_right_align_str(Rect* rect, const char* str, enum OverflowDir overflow_direction);
+void update_text_rect_to_right_align_str(
+    Rect* rect,
+    const char* str,
+    enum OverflowDir overflow_direction
+);
 
-
+/**
-/** 
  * @brief Updates a rect so a string is centered within it.
- * 
+ *
  * @param rect  The rect provided, the provided values are used to determine the center
  *              and it is then updated so the string starting in rect->left is centered
  *              The rect is in number of pixels but should be a multiple of TTE_CHAR_SIZE
  *              so it's a whole number of tiles to fit TTE characters.
- * 
+ *
  * @param str   The string, the center of the string will be at the center of the updated rect.
- * 
+ *
  * @param bias_direction    Which direction to bias when the string can't be evenly centered
  *                          with respect to char tiles.
  *                          Examples:
@@ -177,28 +304,48 @@ void update_text_rect_to_right_align_str(Rect* rect, const char* str, enum Overf
  */
 void update_text_rect_to_center_str(Rect* rect, const char* str, enum ScreenHorzDir bias_direction);
 
-/*Copies 16 bit data from src to dst, applying a palette offset to the data.
+/**
+ * @brief Copies 16 bit data from src to dst, applying a palette offset to the data.
+ *
  * This is intended solely for use with tile8/8bpp data for dst and src.
- * The palette offset allows the tiles to use a different location in the palette
+ * The palette offset allows the tiles to use a different location in the palette * memory
- * memory
+ * This is useful because  grit always loads the palette to the beginning of pal_bg_mem[]
- * This is useful because  grit always loads the palette to the beginning of 
+ *
- * pal_bg_mem[]
+ * @param dst destination charblock
+ *
+ * @param src destination charblock
+ *
+ * @param wcount Number of words to copy
+ *
+ * @param palette_offset palette offset to shift to
  */
 void memcpy16_tile8_with_palette_offset(u16* dst, const u16* src, uint hwcount, u8 palette_offset);
 
-/*Copies 32 bit data from src to dst, applying a palette offset to the data.
+/**
+ * @brief Copies 32 bit data from src to dst, applying a palette offset to the data.
+ *
  * This is intended solely for use with tile8/8bpp data for dst and src.
- * The palette offset allows the tiles to use a different location in the palette
+ * The palette offset allows the tiles to use a different location in the palette memory
- * memory
+ * This is useful because grit always loads the palette to the beginning of pal_bg_mem[]
- * This is useful because  grit always loads the palette to the beginning of 
+ *
- * pal_bg_mem[]
+ * @param dst destination charblock
+ *
+ * @param src destination charblock
+ *
+ * @param wcount Number of words to copy
+ *
+ * @param palette_offset palette offset to shift to
  */
 void memcpy32_tile8_with_palette_offset(u32* dst, const u32* src, uint wcount, u8 palette_offset);
 
-/* Toggles the visibility of the window layers.
+/**
- * win0 and win1 are the visibility states for the two windows.
+ * @brief Toggles the visibility of the window layers.
+ *
  * These windows are primarily used for the shadows on held jokers, consumables and cards.
+ *
+ * @param win0 the visibility state for window 0
+ * @param win1 the visibility state for window 1
  */
 void toggle_windows(bool win0, bool win1);
 
-#endif //GRAPHIC_UTILS_H
+#endif // GRAPHIC_UTILS_H

include/list.h

@@ -1,9 +1,10 @@
-/** @file list.h
+/**
+ * @file list.h
  *
- *  @brief A doubly-linked list
+ * @brief A doubly-linked list
  *
- *  List Implementation
+ * List Implementation
- *  ===================
+ * ===================
  *
  *  - This @ref List operates as a linked list @ref ListNodes. It operates as a regular
  * doubly-linked list but doesn't allocate memory and rather gets @ref ListNodes from a pool.
@@ -13,6 +14,13 @@
 
 #include <stdbool.h>
 
+/**
+ * @def MAX_LIST_NODES
+ * @brief Number of reserved list nodes.
+ *
+ * Number of list nodes available from the pool of @ref ListNode . This should
+ * be set to to the maximum number of list nodes needed at once.
+ */
 #define MAX_LIST_NODES 128
 
 typedef struct ListNode ListNode;

include/util.h

@@ -1,41 +1,33 @@
+/**
+ * @file util.h
+ *
+ * @brief Utilities relating around number string representation and protected arithmatic helper
+ * functions
+ */
 #ifndef UTIL_H
 #define UTIL_H
 
 #include <stdint.h>
 
-
+/**
+ * @def GBLA_UNUSED
+ * @brief A friendly wrapper around the not so friendly looking __attribute__ syntax for ((unused))
+ */
 #define GBLA_UNUSED __attribute__((unused))
 
-static inline int u32_get_digits(uint32_t n) // https://stackoverflow.com/questions/1068849/how-do-i-determine-the-number-of-digits-of-an-integer-in-c
-{
-    if (n < 10) return 1;
-    if (n < 100) return 2;
-    if (n < 1000) return 3;
-    if (n < 10000) return 4;
-    if (n < 100000) return 5;
-    if (n < 1000000) return 6;
-    if (n < 10000000) return 7;
-    if (n < 100000000) return 8;
-    if (n < 1000000000) return 9;
-    return 10;
-}
-
-static inline int get_digits_even(int n)
-{
-    if (n < 100) return 1;
-    if (n < 10000) return 2;
-    if (n < 1000000) return 3;
-    if (n < 100000000) return 4;
-    return 5;
-}
-
 #define UNDEFINED -1
 
+/**
+ * @def NUM_ELEM_IN_ARR
+ * @brief Get the number of elements in an array
+ *
+ * @param arr input array
+ */
 #define NUM_ELEM_IN_ARR(arr) (sizeof(arr) / sizeof((arr)[0]))
 
-#define INT_MAX_DIGITS  11 // strlen(str(INT_MAX)) = strlen("-2147483647")
+#define INT_MAX_DIGITS   11 // strlen(str(INT_MAX)) = strlen("-2147483647")
-#define UINT_MAX_DIGITS 10 // strlen(str(UINT32_MAX)) = strlen("4294967295")
+#define UINT_MAX_DIGITS  10 // strlen(str(UINT32_MAX)) = strlen("4294967295")
-#define UINT8_MAX_DIGITS 3 // strlen(str(UINT8_MAX)) = strlen("255")
+#define UINT8_MAX_DIGITS 3  // strlen(str(UINT8_MAX)) = strlen("255")
 
 #define ONE_K 1000
 #define ONE_M 1000000
@@ -49,36 +41,127 @@ static inline int get_digits_even(int n)
 // so it needs at least this number of chars to be able to display any suffixed number
 #define SUFFIXED_NUM_MIN_REQ_CHARS 4
 
-int int_arr_max(int int_arr[], int size);
+/**
+ * @brief Avoid overflow when adding two u32 integers
+ *
+ * @param a left operator **a + b**
+ * @param b left operator **a + b**
+ *
+ * @return the result of **a + b** or **UINT32_MAX** in case of overflow
+ */
+uint32_t u32_protected_add(uint32_t a, uint32_t b);
 
-/** 
+/**
+ * @brief Avoid overflow when adding two u16 integers
+ *
+ * @param a left operator **a + b**
+ * @param b left operator **a + b**
+ *
+ * @return the result of **a + b** or **UINT16_MAX** in case of overflow
+ */
+uint16_t u16_protected_add(uint16_t a, uint16_t b);
+
+/**
+ * @brief Avoid overflow when multiplying two u32 integers
+ *
+ * @param a left operator **a * b**
+ * @param b left operator **a * b**
+ *
+ * @return the result of **a * b** or **UINT32_MAX** in case of overflow
+ */
+uint32_t u32_protected_mult(uint32_t a, uint32_t b);
+
+/**
+ * @brief Avoid overflow when multiplying two u16 integers
+ *
+ * @param a left operator **a * b**
+ * @param b left operator **a * b**
+ *
+ * @return the result of **a * b** or **UINT16_MAX** in case of overflow
+ */
+uint16_t u16_protected_mult(uint16_t a, uint16_t b);
+
+/**
  * @brief   Truncate an unsigned number into a suffixed string representation e.g. 12000 -> "12K"
  *          The least significant digits are rounded down e.g. 12345 -> "12K", 12987 -> "12K"
- *          
+ *
  * @param num           The number to truncate, can be anything from 0 to UINT32_MAX.
- *  
+ *
  * @param num_req_chars The number of characters to constrain the string to.
  *                      The function will use up as much characters as it can
- *                      in order to maintain as much accuracy as possible. 
+ *                      in order to maintain as much accuracy as possible.
  *                      So numbers are not fully truncated if not necessary,
- *                      e.g. 123123000 -> "123123K" for example value 7, 
+ *                      e.g. 123123000 -> "123123K" for example value 7,
  *                      and if num_req_chars > u32_get_digits(num) the number will not
  *                      be truncated at all.
- *                      Passing less than SUFFIXED_NUM_MIN_REQ_CHARS may result in an 
+ *                      Passing less than SUFFIXED_NUM_MIN_REQ_CHARS may result in an
  *                      output string longer than num_req_chars but
  *                      can be done to truncate 1000s -> "1K", 2000 -> "2K" etc.
  *                      which wouldn't be otherwise.
- *                      
+ *
- * @param out_str       An output buffer to write the resulting string to. 
+ * @param out_str       An output buffer to write the resulting string to.
  *                      Must be of size UINT_MAX_DIGITS + 1. + 1 for null-terminator.
  *                      At that size the suffix character will always be accounted for since
- *                      a number with more digits than UINT_MAX_DIGITS will not be handled nor truncated.
+ *                      a number with more digits than UINT_MAX_DIGITS will not be handled nor
+ *                      truncated.
  */
-void truncate_uint_to_suffixed_str(uint32_t num, int num_req_chars, char out_str[UINT_MAX_DIGITS + 1]);
+void truncate_uint_to_suffixed_str(
+    uint32_t num,
+    int num_req_chars,
+    char out_str_buff[UINT_MAX_DIGITS + 1]
+);
 
-uint32_t u32_protected_add (uint32_t a, uint32_t b);
+/**
-uint16_t u16_protected_add (uint16_t a, uint16_t b);
+ * @brief Get the number of digits in a 32-bit unsigned number
-uint32_t u32_protected_mult(uint32_t a, uint32_t b);
+ * https://stackoverflow.com/questions/1068849/how-do-i-determine-the-number-of-digits-of-an-integer-in-c
-uint16_t u16_protected_mult(uint16_t a, uint16_t b);
+ *
+ * @param n 32-bit unsigned value to find the number of decimal digits of
+ *
+ * @return the number of digits in a number
+ */
+static inline int u32_get_digits(uint32_t n)
+{
+    if (n < 10)
+        return 1;
+    if (n < 100)
+        return 2;
+    if (n < 1000)
+        return 3;
+    if (n < 10000)
+        return 4;
+    if (n < 100000)
+        return 5;
+    if (n < 1000000)
+        return 6;
+    if (n < 10000000)
+        return 7;
+    if (n < 100000000)
+        return 8;
+    if (n < 1000000000)
+        return 9;
+    return 10;
+}
+
+/**
+ * @brief Get the number of digits closest to it's "even" value, i.e. ceil(digits/2)
+ *
+ * Useful for centering text on tiles
+ *
+ * @param n value to find the number of even decimal digits of
+ *
+ * @return The value of ceil(get_digits(n)/2)
+ */
+static inline int get_digits_even(int n)
+{
+    if (n < 100)
+        return 1;
+    if (n < 10000)
+        return 2;
+    if (n < 1000000)
+        return 3;
+    if (n < 100000000)
+        return 4;
+    return 5;
+}
 
 #endif // UTIL_H

source/affine_background.c

@@ -1,57 +1,28 @@
 #include "affine_background.h"
+
 #include "affine_background_gfx.h"
 #include "affine_main_menu_background_gfx.h"
-
 #include "graphic_utils.h"
 
 #define ANIMATION_SPEED_DIVISOR 16
 
-BG_AFFINE bgaff_arr[SCREEN_HEIGHT + 1];
+// Prepare screen during VBLANK
+// Pre-computes the affine matrices values for each scanline and stores in bgaff_arr. This is to be
+// done in VBLANK so the HBLANK code can just fetch the values quickly.
+static IWRAM_CODE void s_affine_background_prep_bgaff_arr();
 
-AFF_SRC_EX asx = {0};
+static BG_AFFINE _bgaff_arr[SCREEN_HEIGHT + 1];
-
+static AFF_SRC_EX _asx = {0};
-enum AffineBackgroundID background = AFFINE_BG_MAIN_MENU;
+static enum AffineBackgroundID _background = AFFINE_BG_MAIN_MENU;
-
+static uint _timer = 0;
-static uint timer = 0;
 
 void affine_background_init()
-{   
+{
     affine_background_update();
 
     REG_BG_AFFINE[AFFINE_BG_IDX] = bg_aff_default;
 }
 
-// Pre-computes the affine matrices values for each scanline 
-// and stores in bgaff_arr. 
-// This is to be done in VBLANK so the HBLANK code 
-// can just fetch the values quickly.
-IWRAM_CODE void affine_background_prep_bgaff_arr()
-{
-    for (u16 vcount = 0; vcount < SCREEN_HEIGHT; vcount++)
-    {
-        const s32 timer_s32 = timer << 8;
-        const s32 vcount_s32 = vcount << 8;
-        const s16 vcount_s16 = vcount;
-        const s32 vcount_sine = lu_sin(vcount_s32 + timer_s32 / ANIMATION_SPEED_DIVISOR); // dividing the timer by 16 to make the animation slower
-        
-        asx.scr_x = (SCREEN_WIDTH / 2); // 128 on x and y is an offset used to center the rotation
-        asx.scr_y = vcount_s16 - (SCREEN_HEIGHT / 2); // scr_y must equal vcount otherwise the background will have no vertical difference
-        asx.tex_x = (1000 * 1000) + (vcount_sine);
-        asx.tex_y = (1000 * 1000);
-        asx.sx = 128;
-        asx.sy = 128;
-        asx.alpha = vcount_sine + (timer_s32 / ANIMATION_SPEED_DIVISOR);
-
-        bg_rotscale_ex(&bgaff_arr[vcount], &asx);
-    }
-
-    /* HBLANK occurs after the scanline so REG_VCOUNT represents the 
-     * the scanline that just passed, so when it's SCREEN_HEIGHT we will
-     * actually be updating the first line
-     */
-    bgaff_arr[SCREEN_HEIGHT] = bgaff_arr[0];
-}
-
 IWRAM_CODE void affine_background_hblank()
 {
     vu16 vcount = REG_VCOUNT;
@@ -62,69 +33,110 @@ IWRAM_CODE void affine_background_hblank()
     }
 
     // See comment in affine_background_prep_bgaff_arr()
-    REG_BG_AFFINE[AFFINE_BG_IDX] = bgaff_arr[vcount + 1];
+    REG_BG_AFFINE[AFFINE_BG_IDX] = _bgaff_arr[vcount + 1];
 }
 
 void affine_background_update()
 {
     if (REG_IE & IRQ_HBLANK) // High quality mode with HBLANK interrupt
     {
-        affine_background_prep_bgaff_arr();
+        s_affine_background_prep_bgaff_arr();
     }
     else // Low quality mode without HBLANK interrupt
     {
-        asx.scr_x = 0;
+        _asx.scr_x = 0;
-        asx.scr_y = 0;
+        _asx.scr_y = 0;
-        asx.tex_x += 5;
+        _asx.tex_x += 5;
-        asx.tex_y += 12;
+        _asx.tex_y += 12;
-        asx.sx = ((lu_sin(timer * 100)) >> 8) + 256; // Scale the sine value to fit in a s16
+        // Scale the sine value to fit in a s16
-        asx.sy = ((lu_sin(timer * 100 + 0x4000)) >> 8) + 256; // Scale the sine value to fit in a s16
+        _asx.sx = ((lu_sin(_timer * 100)) >> 8) + 256;
-        asx.alpha = 0;
+        // Scale the sine value to fit in a s16
+        _asx.sy = ((lu_sin(_timer * 100 + 0x4000)) >> 8) + 256;
+        _asx.alpha = 0;
 
-        bg_rotscale_ex(&bgaff_arr[0], &asx);
+        bg_rotscale_ex(&_bgaff_arr[0], &_asx);
-        REG_BG_AFFINE[AFFINE_BG_IDX] = bgaff_arr[0];
+        REG_BG_AFFINE[AFFINE_BG_IDX] = _bgaff_arr[0];
     }
 
-    timer++;
+    _timer++;
 }
 
 void affine_background_set_color(COLOR color)
 {
-    affine_background_change_background(background); // Reload the palette to reset any previous color scaling
+    // Reload the palette to reset any previous color scaling
+    affine_background_change_background(_background);
     for (int i = 0; i < AFFINE_BG_PAL_LEN; i++)
     {
         clr_rgbscale(&pal_bg_mem[AFFINE_BG_PB] + i, &pal_bg_mem[AFFINE_BG_PB] + i, 1, color);
     }
 }
 
-void affine_background_load_palette(const u16 *src)
+void affine_background_load_palette(const u16* src)
 {
     memcpy16(&pal_bg_mem[AFFINE_BG_PB], src, AFFINE_BG_PAL_LEN);
 }
 
 void affine_background_change_background(enum AffineBackgroundID new_bg)
 {
-    background = new_bg;
+    _background = new_bg;
 
-    switch (background)
+    switch (_background)
     {
-    case AFFINE_BG_MAIN_MENU:
+        case AFFINE_BG_MAIN_MENU:
-        REG_BG2CNT &= ~BG_AFF_32x32;
+            REG_BG2CNT &= ~BG_AFF_32x32;
-        REG_BG2CNT |= BG_AFF_16x16;
+            REG_BG2CNT |= BG_AFF_16x16;
-        REG_IE |= IRQ_HBLANK; // Enable HBLANK
+            REG_IE |= IRQ_HBLANK; // Enable HBLANK
 
-        memcpy32_tile8_with_palette_offset((u32*)&tile8_mem[AFFINE_BG_CBB], (const u32*)affine_main_menu_background_gfxTiles, affine_main_menu_background_gfxTilesLen/4, AFFINE_BG_PB);
+            memcpy32_tile8_with_palette_offset(
-        GRIT_CPY(&se_mem[AFFINE_BG_SBB], affine_main_menu_background_gfxMap);
+                (u32*)&tile8_mem[AFFINE_BG_CBB],
-        affine_background_load_palette(affine_main_menu_background_gfxPal);
+                (const u32*)affine_main_menu_background_gfxTiles,
-        break;
+                affine_main_menu_background_gfxTilesLen / 4,
-    case AFFINE_BG_GAME:
+                AFFINE_BG_PB
-        REG_BG2CNT &= ~BG_AFF_16x16;
+            );
-        REG_BG2CNT |= BG_AFF_32x32;
+            GRIT_CPY(&se_mem[AFFINE_BG_SBB], affine_main_menu_background_gfxMap);
-        REG_IE &= ~IRQ_HBLANK; // Disable HBLANK
+            affine_background_load_palette(affine_main_menu_background_gfxPal);
+            break;
+        case AFFINE_BG_GAME:
+            REG_BG2CNT &= ~BG_AFF_16x16;
+            REG_BG2CNT |= BG_AFF_32x32;
+            REG_IE &= ~IRQ_HBLANK; // Disable HBLANK
 
-        memcpy32_tile8_with_palette_offset((u32*)&tile8_mem[AFFINE_BG_CBB], (const u32*)affine_background_gfxTiles, affine_background_gfxTilesLen/4, AFFINE_BG_PB);
+            memcpy32_tile8_with_palette_offset(
-        GRIT_CPY(&se_mem[AFFINE_BG_SBB], affine_background_gfxMap);
+                (u32*)&tile8_mem[AFFINE_BG_CBB],
-        affine_background_load_palette(affine_background_gfxPal);
+                (const u32*)affine_background_gfxTiles,
-        break;
+                affine_background_gfxTilesLen / 4,
+                AFFINE_BG_PB
+            );
+            GRIT_CPY(&se_mem[AFFINE_BG_SBB], affine_background_gfxMap);
+            affine_background_load_palette(affine_background_gfxPal);
+            break;
     }
-}
+}
+
+static IWRAM_CODE void s_affine_background_prep_bgaff_arr()
+{
+    for (u16 vcount = 0; vcount < SCREEN_HEIGHT; vcount++)
+    {
+        const s32 timer_s32 = _timer << 8;
+        const s32 vcount_s32 = vcount << 8;
+        const s16 vcount_s16 = vcount;
+        const s32 vcount_sine = lu_sin(vcount_s32 + timer_s32 / ANIMATION_SPEED_DIVISOR);
+
+        _asx.scr_x = (SCREEN_WIDTH / 2);
+        // scr_y must equal vcount otherwise the background will have no vertical difference
+        _asx.scr_y = vcount_s16 - (SCREEN_HEIGHT / 2);
+        _asx.tex_x = (1000 * 1000) + (vcount_sine);
+        _asx.tex_y = (1000 * 1000);
+        _asx.sx = 128;
+        _asx.sy = 128;
+        _asx.alpha = vcount_sine + (timer_s32 / ANIMATION_SPEED_DIVISOR);
+
+        bg_rotscale_ex(&_bgaff_arr[vcount], &_asx);
+    }
+
+    /* HBLANK occurs after the scanline so REG_VCOUNT represents the
+     * the scanline that just passed, so when it's SCREEN_HEIGHT we will
+     * actually be updating the first line
+     */
+    _bgaff_arr[SCREEN_HEIGHT] = _bgaff_arr[0];
+}

source/audio_utils.c

@@ -1,8 +1,15 @@
-#include "audio_utils.h"
+#include "audio_utils.h"
-#include <maxmod.h>
+
-
+#include <maxmod.h>
-void play_sfx(mm_word id, mm_word rate)
+
-{
+void play_sfx(mm_word id, mm_word rate)
-    mm_sound_effect sfx = { {id}, rate, 0, SFX_DEFAULT_VOLUME, SFX_DEFAULT_PAN, };
+{
-    mmEffectEx(&sfx);
+    mm_sound_effect sfx = {
-}
+        {id},
+        rate,
+        0,
+        SFX_DEFAULT_VOLUME,
+        SFX_DEFAULT_PAN,
+    };
+    mmEffectEx(&sfx);
+}

source/graphic_utils.c

@@ -1,16 +1,30 @@
-#include <tonc_core.h>
+#include "graphic_utils.h"
-#include <tonc_tte.h>
-#include <tonc_math.h>
 
 #include "util.h"
-#include "graphic_utils.h"
-#include <string.h>
 
-const Rect FULL_SCREENBLOCK_RECT = { 0, 0, SE_ROW_LEN - 1, SE_COL_LEN - 1};
+#include <string.h>
+#include <tonc_core.h>
+#include <tonc_math.h>
+#include <tonc_tte.h>
+
+const Rect FULL_SCREENBLOCK_RECT = {0, 0, SE_ROW_LEN - 1, SE_COL_LEN - 1};
+
+static void clip_se_rect_to_screenblock(Rect* rect);
+static void bg_se_copy_or_move_rect_1_tile_vert(
+    u16 bg_sbb,
+    Rect se_rect,
+    enum ScreenVertDir direction,
+    bool move
+);
+static void main_bg_se_copy_or_move_rect_1_tile_vert(
+    Rect se_rect,
+    enum ScreenVertDir direction,
+    bool move
+);
 
 // Clips a rect of screenblock entries to a specified rect
 // The bounding rect is not required to be within screenblock boundaries
-static void clip_se_rect_to_bounding_rect(Rect* rect, const Rect* bounding_rect)
+static inline void clip_se_rect_to_bounding_rect(Rect* rect, const Rect* bounding_rect)
 {
     rect->right = min(rect->right, bounding_rect->right);
     rect->bottom = min(rect->bottom, bounding_rect->bottom);
@@ -25,14 +39,12 @@ static void clip_se_rect_to_screenblock(Rect* rect)
     clip_se_rect_to_bounding_rect(rect, &FULL_SCREENBLOCK_RECT);
 }
 
-SE main_bg_se_get_se(BG_POINT pos)
+// Clips a rect of screenblock entries to be within one step of
-{
-    return se_mat[MAIN_BG_SBB][pos.y][pos.x];
-}
-
-// Clips a rect of screenblock entries to be within one step of 
 // screenblock boundaries vertically depending on direction.
-static void clip_se_rect_within_step_of_full_screen_vert(Rect* se_rect, enum ScreenVertDir direction)
+static inline void clip_se_rect_within_step_of_full_screen_vert(
+    Rect* se_rect,
+    enum ScreenVertDir direction
+)
 {
     Rect bounding_rect = FULL_SCREENBLOCK_RECT;
     if (direction == SCREEN_UP)
@@ -43,28 +55,19 @@ static void clip_se_rect_within_step_of_full_screen_vert(Rect* se_rect, enum Scr
     {
         bounding_rect.bottom -= 1;
     }
-    
+
     clip_se_rect_to_bounding_rect(se_rect, &bounding_rect);
 }
 
-void main_bg_se_clear_rect(Rect se_rect)
-{
-    if (se_rect.left > se_rect.right)
-        return;
-    // Clip to avoid screenblock overflow
-    clip_se_rect_to_screenblock(&se_rect);
-
-    for (int y = se_rect.top; y < se_rect.bottom; y++)
-    {
-        memset16(&(se_mat[MAIN_BG_SBB][y][se_rect.left]), 0x0000, rect_width(&se_rect));
-    }
-}
-
 // Internal static function to merge implementation of move/copy functions.
-static void bg_se_copy_or_move_rect_1_tile_vert(u16 bg_sbb, Rect se_rect, enum ScreenVertDir direction, bool move)
+static void bg_se_copy_or_move_rect_1_tile_vert(
+    u16 bg_sbb,
+    Rect se_rect,
+    enum ScreenVertDir direction,
+    bool move
+)
 {
-     if (se_rect.left > se_rect.right
+    if (se_rect.left > se_rect.right || (direction != SCREEN_UP && direction != SCREEN_DOWN))
-        || (direction != SCREEN_UP && direction != SCREEN_DOWN))
     {
         return;
     }
@@ -77,9 +80,11 @@ static void bg_se_copy_or_move_rect_1_tile_vert(u16 bg_sbb, Rect se_rect, enum S
 
     for (int y = start; y != end - direction; y -= direction)
     {
-        memcpy16(&(se_mat[bg_sbb][y + direction][se_rect.left]),
+        memcpy16(
-                 &se_mat[bg_sbb][y][se_rect.left],
+            &(se_mat[bg_sbb][y + direction][se_rect.left]),
-                 rect_width(&se_rect));
+            &se_mat[bg_sbb][y][se_rect.left],
+            rect_width(&se_rect)
+        );
     }
 
     if (move)
@@ -88,9 +93,13 @@ static void bg_se_copy_or_move_rect_1_tile_vert(u16 bg_sbb, Rect se_rect, enum S
     }
 }
 
-static void main_bg_se_copy_or_move_rect_1_tile_vert(Rect se_rect, enum ScreenVertDir direction, bool move)
+static void main_bg_se_copy_or_move_rect_1_tile_vert(
+    Rect se_rect,
+    enum ScreenVertDir direction,
+    bool move
+)
 {
-   bg_se_copy_or_move_rect_1_tile_vert(MAIN_BG_SBB, se_rect, direction, move);
+    bg_se_copy_or_move_rect_1_tile_vert(MAIN_BG_SBB, se_rect, direction, move);
 }
 
 void bg_se_copy_rect_1_tile_vert(u16 bg_sbb, Rect se_rect, enum ScreenVertDir direction)
@@ -128,22 +137,18 @@ void main_bg_se_copy_rect(Rect se_rect, BG_POINT dest_pos)
     // Copy the rect to the tile map
     for (int sy = 0; sy < height; sy++)
     {
-        memcpy16(&tile_map[sy][0],
+        memcpy16(&tile_map[sy][0], &se_mat[MAIN_BG_SBB][se_rect.top + sy][se_rect.left], width);
-                 &se_mat[MAIN_BG_SBB][se_rect.top + sy][se_rect.left], 
-                 width);
     }
-    
+
     // TODO: Avoid overflow
     // Copy the tilemap to the new rect position
     for (int sy = 0; sy < height; sy++)
     {
-        memcpy16(&se_mat[MAIN_BG_SBB][dest_pos.y + sy][dest_pos.x],
+        memcpy16(&se_mat[MAIN_BG_SBB][dest_pos.y + sy][dest_pos.x], &tile_map[sy][0], width);
-                 &tile_map[sy][0],
-                 width);
     }
 }
 
-void main_bg_se_fill_rect_with_se(SE se, Rect se_rect)
+static inline void main_bg_se_fill_rect_with_se(SE se, Rect se_rect)
 {
     if (se_rect.left > se_rect.right || se_rect.top > se_rect.bottom)
         return;
@@ -161,7 +166,12 @@ void main_bg_se_fill_rect_with_se(SE se, Rect se_rect)
 }
 
 // Helper: Copy the corners of a 3x3 tile block
-static void main_bg_se_expand_3x3_copy_corners(const Rect* se_dest_rect, const BG_POINT* src_top_left_pnt, int dest_rect_width, int dest_rect_height)
+static inline void main_bg_se_expand_3x3_copy_corners(
+    const Rect* se_dest_rect,
+    const BG_POINT* src_top_left_pnt,
+    int dest_rect_width,
+    int dest_rect_height
+)
 {
     SE top_left_se = se_mat[MAIN_BG_SBB][src_top_left_pnt->y][src_top_left_pnt->x];
     se_mat[MAIN_BG_SBB][se_dest_rect->top][se_dest_rect->left] = top_left_se;
@@ -170,33 +180,53 @@ static void main_bg_se_expand_3x3_copy_corners(const Rect* se_dest_rect, const B
     se_mat[MAIN_BG_SBB][se_dest_rect->top][se_dest_rect->left + dest_rect_width - 1] = top_right_se;
 
     SE bottom_left_se = se_mat[MAIN_BG_SBB][src_top_left_pnt->y + 2][src_top_left_pnt->x];
-    se_mat[MAIN_BG_SBB][se_dest_rect->top + dest_rect_height - 1][se_dest_rect->left] = bottom_left_se;
+    se_mat[MAIN_BG_SBB][se_dest_rect->top + dest_rect_height - 1][se_dest_rect->left] =
+        bottom_left_se;
 
     SE bottom_right_se = se_mat[MAIN_BG_SBB][src_top_left_pnt->y + 2][src_top_left_pnt->x + 2];
-    se_mat[MAIN_BG_SBB][se_dest_rect->top + dest_rect_height - 1][se_dest_rect->left + dest_rect_width - 1] = bottom_right_se;
+    se_mat[MAIN_BG_SBB][se_dest_rect->top + dest_rect_height - 1]
+          [se_dest_rect->left + dest_rect_width - 1] = bottom_right_se;
 }
 
 // Helper: Copy the top and bottom sides of a 3x3 tile block
-static void main_bg_se_expand_3x3_copy_top_bottom(const Rect* se_dest_rect, const BG_POINT* src_top_left_pnt, int dest_rect_width)
+static inline void main_bg_se_expand_3x3_copy_top_bottom(
+    const Rect* se_dest_rect,
+    const BG_POINT* src_top_left_pnt,
+    int dest_rect_width
+)
 {
     if (dest_rect_width > 2)
     {
         SE top_middle_se = se_mat[MAIN_BG_SBB][src_top_left_pnt->y][src_top_left_pnt->x + 1];
         SE bottom_middle_se = se_mat[MAIN_BG_SBB][src_top_left_pnt->y + 2][src_top_left_pnt->x + 1];
-        memset16(&se_mat[MAIN_BG_SBB][se_dest_rect->top][se_dest_rect->left + 1], top_middle_se, dest_rect_width - 2);
+        memset16(
-        memset16(&se_mat[MAIN_BG_SBB][se_dest_rect->bottom][se_dest_rect->left + 1], bottom_middle_se, dest_rect_width - 2);
+            &se_mat[MAIN_BG_SBB][se_dest_rect->top][se_dest_rect->left + 1],
+            top_middle_se,
+            dest_rect_width - 2
+        );
+        memset16(
+            &se_mat[MAIN_BG_SBB][se_dest_rect->bottom][se_dest_rect->left + 1],
+            bottom_middle_se,
+            dest_rect_width - 2
+        );
     }
 }
 
 // Helper: Copy the left and right sides of a 3x3 tile block
-static void main_bg_se_expand_3x3_copy_left_right(const Rect* se_dest_rect, const BG_POINT* src_top_left_pnt, int dest_rect_width, int dest_rect_height)
+static inline void main_bg_se_expand_3x3_copy_left_right(
+    const Rect* se_dest_rect,
+    const BG_POINT* src_top_left_pnt,
+    int dest_rect_width,
+    int dest_rect_height
+)
 {
     SE middle_left_se = se_mat[MAIN_BG_SBB][src_top_left_pnt->y + 1][src_top_left_pnt->x];
     SE middle_right_se = se_mat[MAIN_BG_SBB][src_top_left_pnt->y + 1][src_top_left_pnt->x + 2];
-    for (int y = 1;  y < dest_rect_height - 1; y++)
+    for (int y = 1; y < dest_rect_height - 1; y++)
     {
         se_mat[MAIN_BG_SBB][se_dest_rect->top + y][se_dest_rect->left] = middle_left_se;
-        se_mat[MAIN_BG_SBB][se_dest_rect->top + y][se_dest_rect->left + dest_rect_width - 1] = middle_right_se;
+        se_mat[MAIN_BG_SBB][se_dest_rect->top + y][se_dest_rect->left + dest_rect_width - 1] =
+            middle_right_se;
     }
 }
 
@@ -214,19 +244,34 @@ void main_bg_se_copy_expand_3x3_rect(Rect se_dest_rect, BG_POINT src_top_left_pn
     }
 
     // Copy the corners
-    main_bg_se_expand_3x3_copy_corners(&se_dest_rect, &src_top_left_pnt, dest_rect_width, dest_rect_height);
+    main_bg_se_expand_3x3_copy_corners(
+        &se_dest_rect,
+        &src_top_left_pnt,
+        dest_rect_width,
+        dest_rect_height
+    );
 
     // Copy top and bottom sides
     main_bg_se_expand_3x3_copy_top_bottom(&se_dest_rect, &src_top_left_pnt, dest_rect_width);
 
     // Copy left and right sides
-    main_bg_se_expand_3x3_copy_left_right(&se_dest_rect, &src_top_left_pnt, dest_rect_width, dest_rect_height);
+    main_bg_se_expand_3x3_copy_left_right(
+        &se_dest_rect,
+        &src_top_left_pnt,
+        dest_rect_width,
+        dest_rect_height
+    );
 
     // Fill the center if needed
     if (dest_rect_width > 2 && dest_rect_height > 2)
     {
         SE middle_fill_se = se_mat[MAIN_BG_SBB][src_top_left_pnt.y + 1][src_top_left_pnt.x + 1];
-        Rect dest_inner_fill_rect = {se_dest_rect.left + 1, se_dest_rect.top + 1, se_dest_rect.right - 1, se_dest_rect.bottom - 1};
+        Rect dest_inner_fill_rect = {
+            se_dest_rect.left + 1,
+            se_dest_rect.top + 1,
+            se_dest_rect.right - 1,
+            se_dest_rect.bottom - 1
+        };
         main_bg_se_fill_rect_with_se(middle_fill_se, dest_inner_fill_rect);
     }
 }
@@ -236,7 +281,11 @@ void tte_erase_rect_wrapper(Rect rect)
     tte_erase_rect(rect.left, rect.top, rect.right, rect.bottom);
 }
 
-void update_text_rect_to_right_align_str(Rect* rect, const char* str, enum OverflowDir overflow_direction)
+void update_text_rect_to_right_align_str(
+    Rect* rect,
+    const char* str,
+    enum OverflowDir overflow_direction
+)
 {
     // TODO: Allow passing string length to avoid calling strlen()?
     int str_len = strlen(str);
@@ -249,7 +298,7 @@ void update_text_rect_to_right_align_str(Rect* rect, const char* str, enum Overf
         int num_fitting_chars = rect_width(rect) / TTE_CHAR_SIZE;
         if (str_len < num_fitting_chars)
             rect->left += (num_fitting_chars - str_len) * TTE_CHAR_SIZE;
-        //else nothing is to be updated, entire rect is filled and may overflow
+        // else nothing is to be updated, entire rect is filled and may overflow
     }
 }
 
@@ -283,7 +332,8 @@ void memcpy16_tile8_with_palette_offset(u16* dst, const u16* src, uint hwcount,
 
 void memcpy32_tile8_with_palette_offset(u32* dst, const u32* src, uint wcount, u8 palette_offset)
 {
-    const u32 offset = (palette_offset << 24) | (palette_offset << 16) | (palette_offset << 8) | palette_offset;
+    const u32 offset =
+        (palette_offset << 24) | (palette_offset << 16) | (palette_offset << 8) | palette_offset;
     for (int i = 0; i < wcount; i++)
     {
         // Copying u8 data 4 times across u32 data
@@ -319,4 +369,17 @@ void toggle_windows(bool win0, bool win1)
     {
         REG_BLDCNT = 0;
     }
-}
+}
+
+void main_bg_se_clear_rect(Rect se_rect)
+{
+    if (se_rect.left > se_rect.right)
+        return;
+    // Clip to avoid screenblock overflow
+    clip_se_rect_to_screenblock(&se_rect);
+
+    for (int y = se_rect.top; y < se_rect.bottom; y++)
+    {
+        memset16(&(se_mat[MAIN_BG_SBB][y][se_rect.left]), 0x0000, rect_width(&se_rect));
+    }
+}

source/util.c

@@ -1,7 +1,8 @@
 #include "util.h"
+
 #include <limits.h>
-#include <stdio.h>
 #include <stdbool.h>
+#include <stdio.h>
 
 int int_arr_max(int int_arr[], int size)
 {
@@ -17,7 +18,11 @@ int int_arr_max(int int_arr[], int size)
     return max;
 }
 
-void truncate_uint_to_suffixed_str(uint32_t num, int num_req_chars, char out_str_buff[UINT_MAX_DIGITS + 1])
+void truncate_uint_to_suffixed_str(
+    uint32_t num,
+    int num_req_chars,
+    char out_str_buff[UINT_MAX_DIGITS + 1]
+)
 {
     bool inevitable_overflow = num_req_chars < SUFFIXED_NUM_MIN_REQ_CHARS;
     if (inevitable_overflow)
@@ -28,7 +33,7 @@ void truncate_uint_to_suffixed_str(uint32_t num, int num_req_chars, char out_str
     int num_digits = u32_get_digits(num);
     int overflow_size = num_digits - num_req_chars;
     char* suffix = "";
-    
+
     /* If there is overflow, divide by the next suffixed power of 10
      * to truncate the number back within num_req_chars.
      * UINT32_MAX is in the billions so no need to check larger numbers
@@ -44,9 +49,8 @@ void truncate_uint_to_suffixed_str(uint32_t num, int num_req_chars, char out_str
         num /= ONE_M;
         suffix = "M";
     }
-    else if (overflow_size > 0 
+    else if (overflow_size > 0 || (inevitable_overflow && num_digits == SUFFIXED_NUM_MIN_REQ_CHARS))
-            || (inevitable_overflow && num_digits == SUFFIXED_NUM_MIN_REQ_CHARS)) 
+    // Special case - alleviate inevitable overflow for 1000s and truncate them to "1K"s
-            // Special case - alleviate inevitable overflow for 1000s and truncate them to "1K"s
     {
         num /= ONE_K;
         suffix = "K";
@@ -61,7 +65,7 @@ uint32_t u32_protected_add(uint32_t a, uint32_t b)
 {
     return (a > (UINT32_MAX - b)) ? UINT32_MAX : (a + b);
 }
-    
+
 uint16_t u16_protected_add(uint16_t a, uint16_t b)
 {
     return (a > (UINT16_MAX - b)) ? UINT16_MAX : (a + b);
@@ -75,5 +79,4 @@ uint32_t u32_protected_mult(uint32_t a, uint32_t b)
 uint16_t u16_protected_mult(uint16_t a, uint16_t b)
 {
     return (a == 0 || b == 0) ? 0 : (a > (UINT16_MAX / b) ? UINT16_MAX : a * b);
-
 }

source/version.c

@@ -6,5 +6,4 @@
 #define GIT_DIRTY "-dirty"
 #endif
 
-__attribute__((section(".version"), used))
+__attribute__((section(".version"), used)) const char balatro_version[] = "GBALATRO_VERSION:" GIT_HASH GIT_DIRTY;
-const char balatro_version[] = "GBALATRO_VERSION:" GIT_HASH GIT_DIRTY;