Document z_moji.c (#926)

* Document `z_moji.c`

* Run formatter

* Use `CHAR_HEIGHT` instead of `CHAR_WIDTH` for y pos

* `> X - 1` -> `>= X`

* `const char*` for string argument

* Type palettes and textures with `u64`

* Remove unused variable

* Use `CHAR_WIDTH` and `CHAR_HEIGHT` more

* Explicit documentation on `gMojiFontTex`

data/z_text.data.s

@@ -11,10 +11,10 @@
 
 # temporary file name, rename to something more appropriate when decompiled
 
-glabel gLetterTLUT
+glabel gMojiFontTLUTs
     .incbin "baserom.z64", 0xBA18E0, 0x80
 
-glabel gFontFF
+glabel gMojiFontTex
     .incbin "baserom.z64", 0xBA1960, 0x400
 
 # Unused

include/variables.h

@@ -206,8 +206,9 @@ extern u16 gSramSlotOffsets[];
 //extern ? D_8012A6A4;
 //extern ? D_8012A704;
 //extern ? D_8012A71C;
-extern u8 gLetterTLUT[4][32]; // original name: "moji_tlut"
+// 4 16-colors palettes
-extern u8 gFontFF[]; // original name: "font_ff"
+extern u64 gMojiFontTLUTs[4][4]; // original name: "moji_tlut"
+extern u64 gMojiFontTex[]; // original name: "font_ff"
 //extern ? D_8012AC90;
 //extern ? D_8012ACA0;
 //extern ? D_8012AD20;

src/code/z_moji.c

@@ -1,100 +1,131 @@
+/**
+ * Unused. A very simple utility for drawing text on screen.
+ */
+
 #include "global.h"
 
+// how big to draw the characters on screen
+#define DISP_CHAR_WIDTH 8
+#define DISP_CHAR_HEIGHT 8
+
+// gMojiFontTex is a TEX_CHAR_COLS x TEX_CHAR_ROWS grid of characters,
+// each character being TEX_CHAR_WIDTH x TEX_CHAR_HEIGHT in size.
+// Each spot on the grid contains 4 characters, which are revealed by using different TLUTs.
+
+#define TEX_CHAR_WIDTH 8
+#define TEX_CHAR_HEIGHT 8
+
+#define TEX_CHAR_COLS 2
+#define TEX_CHAR_ROWS 16
+
+// A character `c = 0bRRRRRCTT` maps to row 0bRRRRR, column 0bC and TLUT 0bTT.
+#define GET_CHAR_TLUT_INDEX(c) (c & 3)
+// `/ 4` matches the `& 4` (`(c & 4) / 4` is the column the character is in)
+#define GET_TEX_CHAR_S(c) ((u16)(c & 4) * ((1 << 5) * TEX_CHAR_WIDTH / 4))
+#define GET_TEX_CHAR_T(c) ((u16)(c >> 3) * ((1 << 5) * TEX_CHAR_HEIGHT))
+
 u32 sFontColorRed = 255;
 u32 sFontColorGreen = 255;
 u32 sFontColorBlue = 255;
 u32 sFontColorAlpha = 255;
-s32 D_80120120 = 0;
-s32 D_80120124 = 0;
 
-UNK_TYPE D_8015FFC0;
+s32 sScreenPosX = 0;
-UNK_TYPE D_8015FFC4;
+s32 sScreenPosY = 0;
 
-void func_8007B910(u32 red, u32 green, u32 blue, u32 alpha) {
+s32 sCurTLUTIndex;
+
+void Moji_SetColor(u32 red, u32 green, u32 blue, u32 alpha) {
     sFontColorRed = red;
     sFontColorGreen = green;
     sFontColorBlue = blue;
     sFontColorAlpha = alpha;
 }
 
-void func_8007B934(s32 arg0, s32 arg1) {
+void Moji_SetPosition(s32 gridX, s32 gridY) {
-    if (arg0 > 39) {
+    if (gridX >= SCREEN_WIDTH / DISP_CHAR_WIDTH) {
-        D_80120120 = 39 * 8;
+        sScreenPosX = SCREEN_WIDTH - DISP_CHAR_WIDTH;
-    } else if (arg0 < 0) {
+    } else if (gridX < 0) {
-        D_80120120 = 0;
+        sScreenPosX = 0;
     } else {
-        D_80120120 = arg0 * 8;
+        sScreenPosX = gridX * DISP_CHAR_WIDTH;
     }
 
-    if (arg1 > 29) {
+    if (gridY >= SCREEN_HEIGHT / DISP_CHAR_HEIGHT) {
-        D_80120124 = 29 * 8;
+        sScreenPosY = SCREEN_HEIGHT - DISP_CHAR_HEIGHT;
-    } else if (arg1 < 0) {
+    } else if (gridY < 0) {
-        D_80120124 = 0;
+        sScreenPosY = 0;
     } else {
-        D_80120124 = arg1 * 8;
+        sScreenPosY = gridY * DISP_CHAR_HEIGHT;
     }
 }
 
-void func_8007B9A4(GraphicsContext* gfxCtx, u8 arg1) {
+void Moji_DrawChar(GraphicsContext* gfxCtx, char c) {
     s32 pad[2];
 
     OPEN_DISPS(gfxCtx, "../z_moji.c", 86);
 
-    if ((u32)gLetterTLUT & 0xF) {
+    if ((u32)gMojiFontTLUTs & 0xF) {
-        osSyncPrintf("moji_tlut --> %X\n", gLetterTLUT);
+        osSyncPrintf("moji_tlut --> %X\n", gMojiFontTLUTs);
     }
 
-    if (D_8015FFC0 != (arg1 & 3)) {
+    if (sCurTLUTIndex != GET_CHAR_TLUT_INDEX(c)) {
-        gDPLoadTLUT(POLY_OPA_DISP++, 16, 256, &gLetterTLUT[arg1 & 3]);
+        gDPLoadTLUT(POLY_OPA_DISP++, 16, 256, &gMojiFontTLUTs[GET_CHAR_TLUT_INDEX(c)]);
-        D_8015FFC0 = arg1 & 3;
+        sCurTLUTIndex = GET_CHAR_TLUT_INDEX(c);
     }
-
+    gSPTextureRectangle(POLY_OPA_DISP++, sScreenPosX << 2, sScreenPosY << 2, (sScreenPosX + DISP_CHAR_WIDTH) << 2,
-    gSPTextureRectangle(POLY_OPA_DISP++, D_80120120 << 2, D_80120124 << 2, (D_80120120 + 8) << 2, (D_80120124 + 8) << 2,
+                        (sScreenPosY + DISP_CHAR_HEIGHT) << 2, G_TX_RENDERTILE, GET_TEX_CHAR_S(c), GET_TEX_CHAR_T(c),
-                        G_TX_RENDERTILE, (u16)(arg1 & 4) * 64, (u16)(arg1 >> 3) * 256, 1 << 10, 1 << 10);
+                        (1 << 10) * TEX_CHAR_WIDTH / DISP_CHAR_WIDTH, (1 << 10) * TEX_CHAR_HEIGHT / DISP_CHAR_HEIGHT);
 
     CLOSE_DISPS(gfxCtx, "../z_moji.c", 123);
 }
 
-void func_8007BBA8(GraphicsContext* gfxCtx, u8* arg1) {
+/**
+ * Does not work as is in most cases.
+ * Can work if the render mode, combiner and possibly other settings are set correctly.
+ * For example this works with the render mode used in `GfxPrint_InitDlist`,
+ * and `G_CC_MODULATEI_PRIM` for both combiner cycles.
+ */
+void Moji_DrawString(GraphicsContext* gfxCtx, const char* str) {
     s32 i;
 
     OPEN_DISPS(gfxCtx, "../z_moji.c", 137);
 
-    if ((u32)gFontFF & 0xF) {
+    if ((u32)gMojiFontTex & 0xF) {
-        osSyncPrintf("font_ff --> %X\n", gFontFF);
+        osSyncPrintf("font_ff --> %X\n", gMojiFontTex);
     }
 
     gDPPipeSync(POLY_OPA_DISP++);
     gDPSetPrimColor(POLY_OPA_DISP++, 0, 0, sFontColorRed, sFontColorGreen, sFontColorBlue, sFontColorAlpha);
 
-    gDPLoadTextureBlock_4b(POLY_OPA_DISP++, (s32)gFontFF, G_IM_FMT_CI, 16, 128, 0, G_TX_NOMIRROR | G_TX_WRAP,
+    gDPLoadTextureBlock_4b(POLY_OPA_DISP++, (s32)gMojiFontTex, G_IM_FMT_CI, TEX_CHAR_COLS * TEX_CHAR_WIDTH,
-                           G_TX_NOMIRROR | G_TX_WRAP, G_TX_NOMASK, G_TX_NOMASK, G_TX_NOLOD, G_TX_NOLOD);
+                           TEX_CHAR_ROWS * TEX_CHAR_HEIGHT, 0, G_TX_NOMIRROR | G_TX_WRAP, G_TX_NOMIRROR | G_TX_WRAP,
+                           G_TX_NOMASK, G_TX_NOMASK, G_TX_NOLOD, G_TX_NOLOD);
 
-    D_8015FFC0 = -1;
+    sCurTLUTIndex = -1;
 
-    for (i = 0; arg1[i] != 0; i++) {
+    for (i = 0; str[i] != '\0'; i++) {
-        switch (arg1[i]) {
+        switch (str[i]) {
-            case 9:
+            case '\t':
-                D_80120120 = (((D_80120120 / 8) / 8) + 1) * 8 * 8;
+                sScreenPosX = (((sScreenPosX / DISP_CHAR_WIDTH) / 8) + 1) * DISP_CHAR_WIDTH * 8;
-                if (D_80120120 >= SCREEN_WIDTH) {
+                if (sScreenPosX >= SCREEN_WIDTH) {
-                    D_80120120 = 0;
+                    sScreenPosX = 0;
-                    D_80120124 += 8;
+                    sScreenPosY += DISP_CHAR_HEIGHT;
-                    if (D_80120124 >= SCREEN_HEIGHT) {
+                    if (sScreenPosY >= SCREEN_HEIGHT) {
-                        D_80120124 = 0;
+                        sScreenPosY = 0;
                     }
                 }
                 break;
-            case 10:
+            case '\n':
-            case 13:
+            case '\r':
-                D_80120120 = 0;
+                sScreenPosX = 0;
-                D_80120124 += 8;
+                sScreenPosY += DISP_CHAR_HEIGHT;
-                if (D_80120124 >= SCREEN_HEIGHT) {
+                if (sScreenPosY >= SCREEN_HEIGHT) {
-                    D_80120124 = 0;
+                    sScreenPosY = 0;
                 }
                 break;
             default:
-                func_8007B9A4(gfxCtx, arg1[i]);
+                Moji_DrawChar(gfxCtx, str[i]);
-                D_80120120 += 8;
+                sScreenPosX += DISP_CHAR_WIDTH;
         }
     }