console: fix writing out of bounds and writing unused memory (#229)

* consolidate console documentation and offset usage

introduces helper functions to avoid the repetition and mistakes
logic was verified equivalent or better by hand but not runtime-tested
fixes various issues having to do with out of bounds writes
misc changes to extraneous whitespace noticed during the refactor

* remove somehow broken character

* forgot a word

* remove false doc (mindless copy-paste), extra punctuation

* reword comment for readability

* remove spurious commas

* remove more spurious commas

* ensure con_xres,con_yres multiples of font size

avoids an unwritten right/bottom edge that's not part of a complete tile
this caused graphical issues and inconsistencies between Init and InitEx
document in the function doxygen comment
make values in __console_vipostcb only computed once
ptr directly from the global equal to destbuffer, less indirection

* make new functions inline, making them faster in the callback

---------

Co-authored-by: Dave Murphy <[email protected]>
Co-authored-by: DacoTaco <[email protected]>

Author: 3 people

gc/ogc/console.h

@@ -55,8 +55,8 @@
  * \brief Initializes the console subsystem with given parameters
  *
  * \param[in] framebuffer pointer to the framebuffer used for drawing the characters
- * \param[in] xstart,ystart start position of the console output in pixel
- * \param[in] xres,yres size of the console in pixel
+ * \param[in] xstart,ystart start position of the console output in pixels
+ * \param[in] xres,yres size of the console in pixels. Truncated to a multiple of font size if not already one
  * \param[in] stride size of one line of the framebuffer in bytes
  *
  * \return none
@@ -69,8 +69,8 @@ void CON_Init(void *framebuffer,int xstart,int ystart,int xres,int yres,int stri
  * \param[in] rmode pointer to the video/render mode configuration
  * \param[in] conXOrigin starting pixel in X direction of the console output on the external framebuffer
  * \param[in] conYOrigin starting pixel in Y direction of the console output on the external framebuffer
- * \param[in] conWidth width of the console output 'window' to be drawn
- * \param[in] conHeight height of the console output 'window' to be drawn
+ * \param[in] conWidth width of the console output 'window' to be drawn in pixels. Truncated to a multiple of font width if not already one
+ * \param[in] conHeight height of the console output 'window' to be drawn in pixels. Truncated to a multiple of font height if not already one
  *
  * \return 0 on success, <0 on error
  */
@@ -80,7 +80,7 @@ s32 CON_InitEx(GXRModeObj *rmode, s32 conXOrigin,s32 conYOrigin,s32 conWidth,s32
  * \fn CON_GetMetrics(int *cols, int *rows)
  * \brief retrieve the columns and rows of the current console
  *
- * \param[out] cols,rows number of columns and rows of the current console
+ * \param[out] cols,rows number of columns and rows of the current console in tiles
  *
  * \return none
  */
@@ -90,7 +90,7 @@ void CON_GetMetrics(int *cols, int *rows);
  * \fn CON_GetPosition(int *col, int *row)
  * \brief retrieve the current cursor position of the current console
  *
- * \param[out] col,row current cursor position
+ * \param[out] col,row current cursor position in tiles, 1-indexed
  *
  * \return none
  */
@@ -100,7 +100,7 @@ void CON_GetPosition(int *cols, int *rows);
  * \fn CON_EnableGecko(int channel, int safe)
  * \brief Enable or disable the USB gecko console.
  *
- * \param[in] channel EXI channel, or -1 ¨to disable the gecko console
+ * \param[in] channel EXI channel, or -1 to disable the gecko console
  * \param[in] safe If true, use safe mode (wait for peer)
  *
  * \return none
@@ -152,22 +152,24 @@ typedef struct PrintConsole
 	ConsoleFont font;        ///< Font of the console
 
 	void *destbuffer;        ///< Framebuffer address
-	int con_xres,con_yres,con_stride;
-	int target_x,target_y, tgt_stride;
+	int con_xres, con_yres;  ///< Console buffer width/height in pixels
+	int con_stride;          ///< Size of one row in the console buffer in bytes
+	int target_x, target_y;  ///< Target buffer x/y offset to start the console in pixels
+	int tgt_stride;          ///< Size of one row in the target buffer in bytes
 
-	int cursorX;             ///< Current X location of the cursor (as a tile offset by default)
-	int cursorY;             ///< Current Y location of the cursor (as a tile offset by default)
+	int cursorX;             ///< Current X location of the cursor in the window in tiles, 1-indexed: 1 <= cursorX <= windowWidth, cursorX > windowWidth wraps to the next line and resets to cursorX = 1
+	int cursorY;             ///< Current Y location of the cursor in the window in tiles, 1-indexed
 
 	int prevCursorX;         ///< Internal state
 	int prevCursorY;         ///< Internal state
 
-	int con_cols;            ///< Width of the console hardware layer in characters
-	int con_rows;            ///< Height of the console hardware layer in characters
+	int con_cols;            ///< Width of the console hardware layer in characters (aka tiles)
+	int con_rows;            ///< Height of the console hardware layer in characters (aka tiles)
 
-	int windowX;             ///< Window X location in characters (not implemented)
-	int windowY;             ///< Window Y location in characters (not implemented)
-	int windowWidth;         ///< Window width in characters (not implemented)
-	int windowHeight;        ///< Window height in characters (not implemented)
+	int windowX;             ///< Window X location in tiles, 1-indexed, 1 <= windowX < con_cols
+	int windowY;             ///< Window Y location in tiles, 1-indexed
+	int windowWidth;         ///< Window width in tiles, 1 <= windowWidth <= con_cols
+	int windowHeight;        ///< Window height in tiles
 
 	int tabSize;             ///< Size of a tab
 	unsigned int fg;         ///< Foreground color
@@ -196,10 +198,10 @@ void consoleSetFont(PrintConsole* console, ConsoleFont* font);
 /**
  * @brief Sets the print window.
  * @param console Console to set, if NULL it will set the current console window.
- * @param x X location of the window.
- * @param y Y location of the window.
- * @param width Width of the window.
- * @param height Height of the window.
+ * @param x X location of the window in tiles, 1-indexed
+ * @param y Y location of the window in tiles, 1-indexed
+ * @param width Width of the window in tiles
+ * @param height Height of the window in tiles
  */
 void consoleSetWindow(PrintConsole* console, unsigned int x, unsigned int y, unsigned int width, unsigned int height);