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>
2025-12-07 12:56:39 -08:00
parent 7bd510ee5f
commit 35ecbf33ae
14 changed files with 3765 additions and 317 deletions
@@ -1,16 +1,30 @@
-#include <tonc_core.h>
-#include <tonc_tte.h>
-#include <tonc_math.h>
+#include "graphic_utils.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)
-{
-    return se_mat[MAIN_BG_SBB][pos.y][pos.x];
-}
-
-// Clips a rect of screenblock entries to be within one step of 
+// 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
-        || (direction != SCREEN_UP && direction != SCREEN_DOWN))
+    if (se_rect.left > se_rect.right || (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]),
-                 &se_mat[bg_sbb][y][se_rect.left],
-                 rect_width(&se_rect));
+        memcpy16(
+            &(se_mat[bg_sbb][y + direction][se_rect.left]),
+            &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],
-                 &se_mat[MAIN_BG_SBB][se_rect.top + sy][se_rect.left], 
-                 width);
+        memcpy16(&tile_map[sy][0], &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],
-                 &tile_map[sy][0],
-                 width);
+        memcpy16(&se_mat[MAIN_BG_SBB][dest_pos.y + sy][dest_pos.x], &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(&se_mat[MAIN_BG_SBB][se_dest_rect->bottom][se_dest_rect->left + 1], bottom_middle_se, dest_rect_width - 2);
+        memset16(
+            &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));
+    }
+}