X-Git-Url: https://git.ucc.asn.au/?a=blobdiff_plain;f=Kernel%2Finclude%2Ftpl_drv_video.h;h=bf3d286d86615f8eb2858845f6e5081ee3c7e51e;hb=7163111b434c9677098c9ba38c6838820499473c;hp=23d3907ad55729558b832400b560de2abab0c373;hpb=8bc40333b1401d7616b225945fee53d972c2f418;p=tpg%2Facess2.git

diff --git a/Kernel/include/tpl_drv_video.h b/Kernel/include/tpl_drv_video.h
index 23d3907a..bf3d286d 100644
--- a/Kernel/include/tpl_drv_video.h
+++ b/Kernel/include/tpl_drv_video.h
@@ -29,49 +29,151 @@
  * \extends eTplDrv_IOCtl
  */
 enum eTplVideo_IOCtl {
-	//! \brief Set Mode - (int mode)
-	VIDEO_IOCTL_SETMODE = 4,
-	//! \brief Get Mode - (int *mode)
-	VIDEO_IOCTL_GETMODE,
-	//! \brief Find a matching mode - (tVideo_IOCtl_Mode *info)
+	/**
+	 * ioctl(..., int *mode)
+	 * \brief Get/Set Mode
+	 * \return Current mode ID or -1 on error
+	 * 
+	 * If \a mode is non-NULL, the current video mode is set to \a *mode.
+	 * This updated ID is then returned to the user.
+	 */
+	VIDEO_IOCTL_GETSETMODE = 4,
+	
+	/**
+	 * ioctl(..., tVideo_IOCtl_Mode *info)
+	 * \brief Find a matching mode
+	 * \return 1 if a mode was found, 0 otherwise
+	 * 
+	 * Using avaliable modes matching the \a bpp and \a flags fields
+	 * set the \a id field to the mode id of the mode with the closest
+	 * \a width and \a height.
+	 */
 	VIDEO_IOCTL_FINDMODE,
-	//! \brief Get mode info - (tVideo_IOCtl_Mode *info)
+	
+	/**
+	 * ioctl(..., tVideo_IOCtl_Mode *info)
+	 * \brief Get mode info
+	 * \return 1 if the mode exists, 0 otherwise
+	 * 
+	 * Set \a info's fields to the mode specified by the \a id field.
+	 */
 	VIDEO_IOCTL_MODEINFO,
-	//! \brief Request access to Framebuffer - (void *dest), Return Boolean Success
+	
+	/**
+	 * ioctl(..., tVideo_IOCtl_Pos *pos)
+	 * \brief Sets the cursor position
+	 * \return Boolean success
+	 * 
+	 * Set the text mode cursor position (if it is supported)
+	 * If the \a pos is set to (-1,-1) the cursor is hidden, otherwise
+	 * \a pos MUST be within the current screen size (as given by the
+	 * current mode's tVideo_IOCtl_Mode.width and tVideo_IOCtl_Mode.height
+	 * fields).
+	 */
+	VIDEO_IOCTL_SETCURSOR,
+	
+	/**
+	 * ioctl(..., tVAddr MapTo)
+	 * \brief Request access to Framebuffer
+	 * \return Boolean Success
+	 * 
+	 * Requests the driver to allow the user direct access to the
+	 * framebuffer by mapping it to the supplied address.
+	 * If the driver does not allow this boolean FALSE (0) is returned,
+	 * else if the call succeeds (and the framebuffer ends up mapped) boolean
+	 * TRUE (1) is returned.
+	 */
 	VIDEO_IOCTL_REQLFB
 };
 
 /**
- \struct sVideo_IOCtl_Mode
- \brief Mode Structure used in IOCtl Calls
-*/
-struct sVideo_IOCtl_Mode {
-	short	id;		//!< Mide ID
+ * \brief Mode Structure used in IOCtl Calls
+ * 
+ * Defines a video mode supported by (or requested of) this driver (depending
+ * on what ioctl call is used)
+ */
+typedef struct sVideo_IOCtl_Mode
+{
+	short	id;		//!< Mode ID
 	Uint16	width;	//!< Width
 	Uint16	height;	//!< Height
-	Uint16	bpp;	//!< Bits per Pixel
-};
-typedef struct sVideo_IOCtl_Mode	tVideo_IOCtl_Mode;	//!< Mode Type
+	Uint8	bpp;	//!< Bits per Unit (Character or Pixel, depending on \a flags)
+	Uint8	flags;	//!< Mode Flags
+}	tVideo_IOCtl_Mode;
+
+//! \name Video Mode flags
+//! \{
+/**
+ * \brief Text Mode Flag
+ * \note A text mode should have the ::sVideo_IOCtl_Mode.bpp set to 12
+ */
+#define VIDEO_FLAG_TEXT	0x1
+/**
+ * \brief Slow (non-accellerated mode)
+ */
+#define VIDEO_FLAG_SLOW	0x2
+//! \}
+
+/**
+ * \brief Describes a position in the video framebuffer
+ */
+typedef struct sVideo_IOCtl_Pos
+{
+	Sint16	x;	//!< X Coordinate
+	Sint16	y;	//!< Y Coordinate
+}	tVideo_IOCtl_Pos;
 
 /**
- * \struct sVT_Char
  * \brief Virtual Terminal Representation of a character
  */
-struct sVT_Char {
-	Uint32	Ch;
+typedef struct sVT_Char
+{
+	Uint32	Ch;	//!< UTF-32 Character
 	union {
 		struct {
-			Uint16	BGCol;
-			Uint16	FGCol;
+			Uint16	BGCol;	//!< 12-bit Foreground Colour
+			Uint16	FGCol;	//!< 12-bit Background Colour
 		};
-		Uint32	Colour;
+		Uint32	Colour;	//!< Compound colour for ease of access
 	};
-};
-typedef struct sVT_Char	tVT_Char;
+}	tVT_Char;
 
+/**
+ * \name Basic builtin colour definitions
+ * \{
+ */
 #define	VT_COL_BLACK	0x0000
 #define	VT_COL_GREY		0x0888
 #define	VT_COL_LTGREY	0x0CCC
 #define	VT_COL_WHITE	0x0FFF
+/**
+ * \}
+ */
+
+//! \brief Defines the width of a rendered character
+extern int	giVT_CharWidth;
+//! \brief Defines the height of a rendered character
+extern int	giVT_CharHeight;
+/**
+ * \fn void VT_Font_Render(Uint32 Codepoint, void *Buffer, int Pitch, Uint32 BGC, Uint32 FGC)
+ * \brief Driver helper that renders a character to a buffer
+ * \param Codepoint	Unicode character to render
+ * \param Buffer	Buffer to render to (32-bpp)
+ * \param Pitch	Number of DWords per line
+ * \param BGC	32-bit Background Colour
+ * \param FGC	32-bit Foreground Colour
+ * 
+ * This function is provided to help video drivers to support a simple
+ * text mode by keeping the character rendering abstracted from the driver,
+ * easing the driver development and reducing code duplication.
+ */
+extern void	VT_Font_Render(Uint32 Codepoint, void *Buffer, int Pitch, Uint32 BGC, Uint32 FGC);
+/**
+ * \fn Uint32 VT_Colour12to24(Uint16 Col12)
+ * \brief Converts a colour from 12bpp to 32bpp
+ * \param Col12	12-bpp input colour
+ * \return Expanded 32-bpp (24-bit colour) version of \a Col12
+ */
+extern Uint32	VT_Colour12to24(Uint16 Col12);
 
 #endif