From 01730a3eca803382c65027740471120e642d9d4f Mon Sep 17 00:00:00 2001
From: Wayne Venables <github@codaris.com>
Date: Sun, 5 Mar 2023 12:28:27 -0800
Subject: [PATCH] Canvas documentation

---
 src/picovga.h     |   1 +
 src/util/canvas.h | 282 ++++++++++++++++++++++++++++++++--------------
 2 files changed, 196 insertions(+), 87 deletions(-)

diff --git a/src/picovga.h b/src/picovga.h
index 566b4dd..b9b3002 100644
--- a/src/picovga.h
+++ b/src/picovga.h
@@ -17,6 +17,7 @@
 /// @defgroup Screen Screen Layout
 /// @defgroup Layers Overlay Layers
 /// @defgroup Colors Colors and Palettes
+/// @defgroup Canvas Canvas
 
 typedef signed char s8;
 typedef unsigned char u8;
diff --git a/src/util/canvas.h b/src/util/canvas.h
index fff6ef2..620cf28 100644
--- a/src/util/canvas.h
+++ b/src/util/canvas.h
@@ -10,133 +10,241 @@
 
 #define DRAW_HWINTER	1	// 1=use hardware interpolator to draw images
 
+/**
+ * @addtogroup Canvas
+ * @brief Drawing board for shapes and images
+ * @details Canvas is a drawing board. It is a support library for working with graphical surfaces and images (see the canvas.h 
+ * file in the _picovga\util folder). The sCanvas structure is a set of parameters that describe the graphical surface, for use 
+ * in drawing functions. A graphical surface can be either a graphical frame buffer or an image, even in Flash. To draw in a 
+ * graphical surface, first attach a canvas to it as a definition describing the structure of the area. Likewise, if you want 
+ * to draw an image to the surface, first create a canvas for the image with its parameters. The parameters are a pointer to
+ * the image data, the image dimensions, and the format. The drawing area can be a graphic area with a depth of 1, 2, 4, 8 bits 
+ * or with attributes. In the case of drawing an image to a canvas, the source and target canvas must have the same format. 
+ * In the case of transformation matrices, only an 8-bit graphic format can be drawn.
+ * @note In PicoVGA, a default canvas 'Canvas' is available. A graphic frame buffer is automatically attached to it when 
+ * initialized with the Video function. Otherwise, it can be used arbitrarily in the program.
+ * @{
+*/
+
 // canvas format
 //   Note: do not use enum, symbols could not be used by the preprocessor
-#define CANVAS_8	0	// 8-bit pixels
-#define CANVAS_4	1	// 4-bit pixels
-#define CANVAS_2	2	// 2-bit pixels
+#define CANVAS_8	0	///< 8-bit pixels
+#define CANVAS_4	1	///< 4-bit pixels
+#define CANVAS_2	2	///< 2-bit pixels
 #define CANVAS_1	3	// 1-bit pixels
-#define CANVAS_PLANE2	4	// 4 colors on 2 planes
-#define CANVAS_ATTRIB8	5	// 2x4 bit color attributes per 8x8 pixel sample
-				//  draw functions:	bit 0..3 = draw color
-				//			bit 4 = draw color is background color
+#define CANVAS_PLANE2	4	///< 4 colors on 2 planes
+#define CANVAS_ATTRIB8	5	///< 2x4 bit color attributes per 8x8 pixel sample
+							///< draw functions: bit 0..3 = draw color
+							///< bit 4 = draw color is background color
 
-// canvas descriptor
+/// Canvas descriptor
 typedef struct {
-	u8*	img;	// image data
-	u8*	img2;	// image data 2 (2nd plane of CANVAS_PLANE2, attributes of CANVAS_ATTRIB8)
-	int	w;	// width
-	int	h;	// height
-	int	wb;	// pitch (bytes between lines)
-	u8	format;	// canvas format CANVAS_*
+	u8*	img;		///< Image data
+	u8*	img2;		///< Image data 2 (2nd plane of CANVAS_PLANE2, attributes of CANVAS_ATTRIB8)
+	int	w;			///< Width
+	int	h;			///< Height
+	int	wb;			///< Pitch (bytes between lines)
+	u8	format;		///< Canvas format CANVAS_*
 } sCanvas;
 
-// Draw rectangle
+/**
+ * @brief Draw rectangle 
+ * @param canvas Canvas
+ * @param x Horizontal position
+ * @param y Veritical position
+ * @param w Width
+ * @param h Height
+ * @param col Color
+*/
 void DrawRect(sCanvas* canvas, int x, int y, int w, int h, u8 col);
 
-// Draw frame
+/**
+ * @brief Draw frame of 1 pixel thickness
+ * @param canvas Canvas
+ * @param x Horizontal position
+ * @param y Veritical position
+ * @param w Width
+ * @param h Height
+ * @param col Color
+*/
 void DrawFrame(sCanvas* canvas, int x, int y, int w, int h, u8 col);
 
-// clear canvas (fill with black color)
+/**
+ * @brief Clear canvas (fill with black color)
+ * @param canvas Canvas
+*/
 void DrawClear(sCanvas* canvas);
 
-// Draw point
+/**
+ * @brief Draw a pixel
+ * @param canvas Canvas
+ * @param x Horizontal position
+ * @param y Veritical position
+ * @param col Color
+*/
 void DrawPoint(sCanvas* canvas, int x, int y, u8 col);
 
-// Draw line
+/**
+ * @brief Draw a line
+ * @param canvas Canvas
+ * @param x1 Horizontal start position
+ * @param y1 Veritical start position
+ * @param x2 Horizontal end position
+ * @param y2 Veritical end position
+ * @param col Color
+*/
 void DrawLine(sCanvas* canvas, int x1, int y1, int x2, int y2, u8 col);
 
-// Draw filled circle
-//  x0, y0 ... coordinate of center
-//  r ... radius
-//  col ... color
-//     col with CANVAS_ATTRIB8 format: bit 0..3 = draw color, bit 4 = draw color is background color
-//  mask ... mask of used octants (0xff = 255 = draw whole circle)
-//         . B2|B1 .
-//       B3 .  |  . B0
-//       ------o------
-//       B4 .  |  . B7
-//         . B5|B6 .
+/**
+ * @brief Draw filled circle
+ * @param canvas Canvas
+ * @param x0 Horizontal center coordinate
+ * @param y0 Veritical center coordinate
+ * @param r Radius
+ * @param col Color (with CANVAS_ATTRIB8 format: bit 0..3 = draw color, bit 4 = draw color is background color)
+ * @param mask Mask.  Specifies, using bits 0 to 7, which eighths of the circle are drawn. 
+ * <pre>
+ *         . B2|B1 .
+ *       B3 .  |  . B0
+ *       ------o------
+ *       B4 .  |  . B7
+ *         . B5|B6 .
+ * </pre>
+*/
 void DrawFillCircle(sCanvas* canvas, int x0, int y0, int r, u8 col, u8 mask=0xff);
 
-// Draw circle
-//  x0, y0 ... coordinate of center
-//  r ... radius
-//  col ... color
-//     col with CANVAS_ATTRIB8 format: bit 0..3 = draw color, bit 4 = draw color is background color
-//  mask ... mask of used octants (0xff = 255 = draw whole circle)
-//         . B2|B1 .
-//       B3 .  |  . B0
-//       ------o------
-//       B4 .  |  . B7
-//         . B5|B6 .
+/**
+ * @brief Draw circle
+ * @param canvas Canvas
+ * @param x0 Horizontal center coordinate
+ * @param y0 Veritical center coordinate
+ * @param r Radius
+ * @param col Color (with CANVAS_ATTRIB8 format: bit 0..3 = draw color, bit 4 = draw color is background color)
+ * @param mask Mask.  Specifies, using bits 0 to 7, which eighths of the circle are drawn. 
+ * <pre>
+ *         . B2|B1 .
+ *       B3 .  |  . B0
+ *       ------o------
+ *       B4 .  |  . B7
+ *         . B5|B6 .
+ * </pre>
+*/
 void DrawCircle(sCanvas* canvas, int x0, int y0, int r, u8 col, u8 mask=0xff);
 
-// Draw text (transparent background)
-//   font = pointer to 1-bit font
+/**
+ * @brief Draw text (transparent background)
+ * @param canvas Canvas
+ * @param text C string to draw
+ * @param x Horizontal position
+ * @param y Verticle position
+ * @param col Text color
+ * @param font Pointer to 1-bit font
+ * @param fontheight Height of font in pixels (default 8)
+ * @param scalex Magnification scale in X dimension
+ * @param scaley Magnification scale in Y dimension
+*/
 void DrawText(sCanvas* canvas, const char* text, int x, int y, u8 col,
 	const void* font, int fontheight=8, int scalex=1, int scaley=1);
 
-// Draw text with background
-//   font = pointer to 1-bit font
+/**
+ * @brief Draw text with background color
+ * @param canvas Canvas
+ * @param text C string to draw
+ * @param x Horizontal position
+ * @param y Verticle position
+ * @param col Text color
+ * @param bgcol Background color
+ * @param font Pointer to 1-bit font
+ * @param fontheight Height of font in pixels (default 8)
+ * @param scalex Magnification scale in X dimension
+ * @param scaley Magnification scale in Y dimension
+*/
 void DrawTextBg(sCanvas* canvas, const char* text, int x, int y, u8 col, u8 bgcol,
 	const void* font, int fontheight=8, int scalex=1, int scaley=1);
 
-// Draw image
+/**
+ * @brief Draw image (without transparency)
+ * @param canvas Destination canvas
+ * @param src Source canvas
+ * @param xd Destination horizontal postion
+ * @param yd Destination vertical position
+ * @param xs Source horizontal position
+ * @param ys Source vertical position
+ * @param w Width
+ * @param h Height
+*/
 void DrawImg(sCanvas* canvas, sCanvas* src, int xd, int yd, int xs, int ys, int w, int h);
 
-// Draw image with transparency (source and destination must have same format, col = transparency key color)
-//  CANVAS_ATTRIB8 format replaced by DrawImg function
+/**
+ * @brief Draw image with transparency
+ * @note Source and destination must have same format.  CANVAS_ATTRIB8 format replaced by DrawImg() function.
+ * @param canvas Destination canvas
+ * @param src Source canvas
+ * @param xd Destination horizontal postion
+ * @param yd Destination vertical position
+ * @param xs Source horizontal position
+ * @param ys Source vertical position
+ * @param w Width
+ * @param h Height
+ * @param col Transparency key color
+*/
 void DrawBlit(sCanvas* canvas, sCanvas* src, int xd, int yd, int xs, int ys, int w, int h, u8 col);
 
-// DrawImgMat mode
+/// DrawImgMat mode
 enum {
-	DRAWIMG_WRAP,		// wrap image
-	DRAWIMG_NOBORDER,	// no border (transparent border)
-	DRAWIMG_CLAMP,		// clamp image (use last pixel as border)
-	DRAWING_COLOR,		// color border
-	DRAWIMG_TRANSP,		// transparent image with key color
-	DRAWIMG_PERSP,		// perspective floor
+	DRAWIMG_WRAP,		///< Wrap image
+	DRAWIMG_NOBORDER,	///< No border (transparent border)
+	DRAWIMG_CLAMP,		///< Clamp image (use last pixel as border)
+	DRAWING_COLOR,		///< Color border
+	DRAWIMG_TRANSP,		///< Transparent image with key color
+	DRAWIMG_PERSP,		///< Perspective floor
 };
 
-// draw 8-bit image with 2D transformation matrix
-//  canvas ... destination canvas
-//  src ... source canvas with image
-//  x ... destination coordinate X
-//  y ... destination coordinate Y
-//  w ... destination width
-//  h ... destination height
-//  m ... transformation matrix (should be prepared using PrepDrawImg or PrepDrawPersp function)
-//  mode ... draw mode DRAWIMG_*
-//  color ... key or border color
-// Note to wrap and perspective mode: Width and height of source image must be power of 2!
+/**
+ * @brief Draw 8-bit image with 2D transformation matrix
+ * @note To wrap and perspective mode: Width and height of source image must be power of 2.
+ * @param canvas Destination canvas
+ * @param src Source canvas with image
+ * @param x Destination horizontal postion
+ * @param y Destination vertical position
+ * @param w Destination width
+ * @param h Destination height
+ * @param m Transformation matrix (should be prepared using PrepDrawImg() or PrepDrawPersp() function)
+ * @param col Key or border color
+*/
 void DrawImgMat(sCanvas* canvas, const sCanvas* src, int x, int y, int w, int h,
 	const class cMat2Df* m, u8 mode, u8 color);
 
-// draw tile map using perspective projection
-//  canvas ... destination canvas
-//  src ... source canvas with column of 8-bit square tiles (width = tile size, must be power of 2)
-//  map ... byte map of tile indices
-//  mapwbits ... number of bits of map width (number of tiles; width must be power of 2)
-//  maphbits ... number of bits of map height (number of tiles; height must be power of 2)
-//  tilebits ... number of bits of tile size (e.g. 5 = tile 32x32 pixel)
-//  x ... destination coordinate X
-//  y ... destination coordinate Y
-//  w ... destination width
-//  h ... destination height
-//  mat ... transformation matrix (should be prepared using PrepDrawPersp function)
-//  horizon ... horizon offset (0=do not use perspective projection)
+/**
+ * @brief Draw tile map using perspective projection
+ * @param canvas Destination canvas
+ * @param src Source canvas with column of 8-bit square tiles (width = tile size, must be power of 2)
+ * @param map Byte map of tile indices
+ * @param mapwbits Number of bits of map width (number of tiles; width must be power of 2)
+ * @param maphbits Number of bits of map height (number of tiles; height must be power of 2)
+ * @param tilebits Number of bits of tile size (e.g. 5 = tile 32x32 pixel)
+ * @param x Destination horizontal postion
+ * @param y Destination vertical position
+ * @param w Destination width
+ * @param h Destination height
+ * @param mat Transformation matrix (should be prepared using PrepDrawPersp() function)
+ * @param horizon Horizon offset (0 = do not use perspective projection)
+*/
 void DrawTileMap(sCanvas* canvas, const sCanvas* src, const u8* map, int mapwbits, int maphbits,
 	int tilebits, int x, int y, int w, int h, const cMat2Df* mat, u8 horizon);
 
-// draw image line interpolated
-//  canvas = destination canvas (8-bit pixel format)
-//  src = source canvas (source image in 8-bit pixel format)
-//  xd,yd = destination coordinates
-//  xs,ys = source coordinates
-//  wd = destination width
-//  ws = source width
-// Overflow in X direction is not checked!
+/**
+ * @brief Draw image line interpolated
+ * @note Overflow in X direction is not checked
+ * @param canvas Destination canvas (8-bit pixel format)
+ * @param src Source canvas (source image in 8-bit pixel format)
+ * @param xd Destination horizontal postion
+ * @param yd Destination vertical position
+ * @param xs Source horizontal position
+ * @param ys Source vertical position
+ * @param wd Destination width
+ * @param ws Source width
+*/
 void DrawImgLine(sCanvas* canvas, sCanvas* src, int xd, int yd, int xs, int ys, int wd, int ws);
 
 #endif // _CANVAS_H