X-Git-Url: https://git.ucc.asn.au/?a=blobdiff_plain;f=Kernel%2Finclude%2Ftpl_drv_video.h;h=f518e74a4de842d1960b9750a562f92556e9faed;hb=23711190d936735f4bd6bd5550d1c99be5358a69;hp=0272078e15edc02775ca38939806bf156d1f64ae;hpb=75e87cf46a3899f76bae5c64e130cfc033562e9a;p=tpg%2Facess2.git

diff --git a/Kernel/include/tpl_drv_video.h b/Kernel/include/tpl_drv_video.h
index 0272078e..f518e74a 100644
--- a/Kernel/include/tpl_drv_video.h
+++ b/Kernel/include/tpl_drv_video.h
@@ -12,12 +12,18 @@
  * but they may choose not to allow direct user access to the framebuffer.
  * 
  * \section Screen Contents
- * Reads and writes to the driver's file while in component colour modes
+ * Writes to the driver's file while in component colour modes
  * must correspond to a change of the contents of the screen. The framebuffer
  * must start at offset 0 in the file.
- * In pallete colour modes the LFB is preceded by a 1024 byte pallete (allowing
- * room for 256 entries of 32-bits each)
-*/
+ * Reading from the screen must either return zero, or read from the
+ * framebuffer.
+ * 
+ * \section Mode Support
+ * All video drivers must support at least one text mode (Mode #0)
+ * For each graphics mode the driver exposes, there must be a corresponding
+ * text mode with the same resolution, this mode will be used when the
+ * user switches to a text Virtual Terminal while in graphics mode.
+ */
 #ifndef _TPL_VIDEO_H
 #define _TPL_VIDEO_H
 
@@ -29,59 +35,196 @@
  * \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 Sets the cursor position (tVideo_IOCtl_Pos *pos)
+	
+	/**
+	 * ioctl(..., int *NewFormat)
+	 * \brief Switches between Text, Framebuffer and 3D modes
+	 * \param NewFormat	Pointer to the new format code (see eTplVideo_BufFormats)
+	 * \return Original format
+	 * 
+	 * Enabes and disables the video text mode, changing the behavior of
+	 * writes to the device file.
+	 */
+	VIDEO_IOCTL_SETBUFFORMAT,
+	
+	/**
+	 * 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,
-	//! \brief Request access to Framebuffer - (void *dest), Return Boolean Success
-	VIDEO_IOCTL_REQLFB
+	
+	/**
+	 * ioctl(..., tVideo_IOCtl_Bitmap *Image)
+	 * \brief Sets the cursor image
+	 * \return Boolean success
+	 *
+	 * Sets the graphics mode cursor image
+	 */
+	VIDEO_IOCTL_SETCURSORBITMAP
 };
+#define DRV_VIDEO_IOCTLNAMES	"getset_mode", "find+mode", "mode_info", "set_buf_format", "set_cursor", "set_cursor_bitmap"
 
 /**
  * \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)
  */
-struct sVideo_IOCtl_Mode {
-	short	id;		//!< Mide ID
+typedef struct sVideo_IOCtl_Mode
+{
+	short	id;		//!< Mode ID
 	Uint16	width;	//!< Width
 	Uint16	height;	//!< Height
-	Uint8	bpp;	//!< Bits per Pixel
+	Uint8	bpp;	//!< Bits per Unit (Character or Pixel, depending on \a flags)
 	Uint8	flags;	//!< Mode Flags
-};
-typedef struct sVideo_IOCtl_Mode	tVideo_IOCtl_Mode;	//!< Mode Type
+}	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
+ * \brief Buffer Format Codes
  */
-#define VIDEO_FLAG_TEXT	0x1
+enum eTplVideo_BufFormats
+{
+	/**
+	 * \brief Text Mode
+	 * 
+	 * The device file presents itself as an array of ::tVT_Char
+	 * each describing a character cell on the screen.
+	 * These cells are each \a giVT_CharWidth pixels wide and
+	 * \a giVT_CharHeight high.
+	 */
+	VIDEO_BUFFMT_TEXT,
+	/**
+	 * \brief Framebuffer Mode
+	 * 
+	 * The device file presents as an array of 32-bpp pixels describing
+	 * the entire screen. The format of a single pixel is in xRGB format
+	 * (top 8 bits ignored, next 8 bits red, next 8 bits green and
+	 * the bottom 8 bits blue)
+	 */
+	VIDEO_BUFFMT_FRAMEBUFFER,
+	/**
+	 * \brief 2D Accelerated Mode
+	 * 
+	 * The device file acts as a character device, accepting a stream of
+	 * commands described in eTplVideo_2DCommands when written to.
+	 */
+	VIDEO_BUFFMT_2DSTREAM,
+	/**
+	 * \brief 3D Accelerated Mode
+	 * 
+	 * The device file acts as a character device, accepting a stream of
+	 * commands described in eTplVideo_3DCommands when written to.
+	 */
+	VIDEO_BUFFMT_3DSTREAM
+};
+
 /**
- * \brief Slow (non-accellerated mode)
+ * \brief 2D Accellerated Video Commands
+ * 
+ * Commands passed in the command stream for ::VIDEO_BUFFMT_2DSTREAM
  */
-#define VIDEO_FLAG_SLOW	0x2
-//! \}
+enum eTplVideo_2DCommands
+{
+	/**
+	 * \brief No Operation
+	 */
+	VIDEO_2DOP_NOP,
+	/**
+	 * \brief Fill a region
+	 * \param X	Uint16 - Leftmost pixels of the region
+	 * \param Y	Uint16 - Topmost pixels of the region
+	 * \param W	Uint16 - Width of the region
+	 * \param H	Uint16 - Height of the region
+	 * \param Colour	Uint32 - Value to fill with
+	 */
+	VIDEO_2DOP_FILL,
+	/**
+	 * \brief Copy a region from one part of the framebuffer to another
+	 * \param DestX	Uint16 - Leftmost pixels of the destination
+	 * \param DestY	Uint16 - Topmost pixels of the destination
+	 * \param SrcX	Uint16 - Leftmost pixels of the source
+	 * \param SrcY	Uint16 - Topmost pixels of the source
+	 * \param Width	Uint16 - Width of the region
+	 * \param Height	Uint16 - Height of the region
+	 */
+	VIDEO_2DOP_BLIT,
+
+
+	/**
+	 * \brief Copy a region from video memory to the framebuffer
+	 */
+	VIDEO_2DOP_BLITBUF,
+
+	/**
+	 * \brief Copy and scale a region from video memory to the framebuffer
+	 */
+	VIDEO_2DOP_BLITSCALEBUF,
+
+	NUM_VIDEO_2DOPS
+};
 
 /**
  * \brief Describes a position in the video framebuffer
  */
-typedef struct sVideo_IOCtl_Pos	tVideo_IOCtl_Pos;
-struct sVideo_IOCtl_Pos {
+typedef struct sVideo_IOCtl_Pos
+{
 	Sint16	x;	//!< X Coordinate
 	Sint16	y;	//!< Y Coordinate
-};
+}	tVideo_IOCtl_Pos;
+
+/**
+ * \brief Bitmap object (out of band image)
+ */
+typedef struct sVideo_IOCtl_Bitmap
+{
+	Sint16	W;	//!< Width of image
+	Sint16	H;	//!< Height of image
+	Sint16	XOfs;	//!< X Offset of center
+	Sint16	YOfs;	//!< Y Offset of center
+	Uint32	Data[];	//!< Image data (ARGB array)
+}	tVideo_IOCtl_Bitmap;
 
 /**
  * \brief Virtual Terminal Representation of a character
  */
-typedef struct sVT_Char	tVT_Char;
-struct sVT_Char {
+typedef struct sVT_Char
+{
 	Uint32	Ch;	//!< UTF-32 Character
 	union {
 		struct {
@@ -90,7 +233,7 @@ struct sVT_Char {
 		};
 		Uint32	Colour;	//!< Compound colour for ease of access
 	};
-};
+}	tVT_Char;
 
 /**
  * \name Basic builtin colour definitions
@@ -109,21 +252,89 @@ 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 Renders a character to a buffer
+ * \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 Buffer	Buffer to render to
+ * \param Depth	Bit depth of the destination buffer
+ * \param Pitch	Number of bytes 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);
+extern void	VT_Font_Render(Uint32 Codepoint, void *Buffer, int Depth, int Pitch, Uint32 BGC, Uint32 FGC);
 /**
  * \fn Uint32 VT_Colour12to24(Uint16 Col12)
- * \brief Converts a colour from 12bpp to 32bpp
+ * \brief Converts a colour from 12bpp to 24bpp
  * \param Col12	12-bpp input colour
- * \return	Expanded 32-bpp (24-bit colour) version of \a Col12
+ * \return Expanded 32-bpp (24-bit colour) version of \a Col12
  */
 extern Uint32	VT_Colour12to24(Uint16 Col12);
+/**
+ * \brief Converts a colour from 12bpp to 14bpp
+ * \param Col12	12-bpp input colour
+ * \return 15 bits per pixel value
+ */
+extern Uint16	VT_Colour12to15(Uint16 Col12);
+/**
+ * \brief Converts a colour from 12bpp to 32bpp
+ * \param Col12	12-bpp input colour
+ * \param Depth	Desired bit depth
+ * \return \a Depth bit number, denoting Col12
+ * 
+ * Expands the source colour into a \a Depth bits per pixel representation.
+ * The colours are expanded with preference to Green, Blue and Red in that order
+ * (so, green gets the first spare pixel, blue gets the next, and red never gets
+ * the spare). \n
+ * The final bit of each component is used to fill the lower bits of the output.
+ */
+extern Uint32	VT_Colour12toN(Uint16 Col12, int Depth);
+
+/**
+ * \brief Handlers for eTplVideo_2DCommands
+ */
+typedef struct sDrvUtil_Video_2DHandlers
+{
+	/**
+	 * \brief No Operation, Ignored
+	 * \see VIDEO_2DOP_NOP
+	 */
+	void	*Nop;
+	/**
+	 * \brief Fill a buffer region
+	 * \param X	Lefthand edge
+	 * \param Y	Top edge
+	 * \param W	Width
+	 * \param H	Height
+	 * \param Colour	Colour to fill with
+	 * \see VIDEO_2DOP_FILL
+	 */
+	void	(*Fill)(void *Ent, Uint16 X, Uint16 Y, Uint16 W, Uint16 H, Uint32 Colour);
+	/**
+	 * \brief Fill a buffer region
+	 * \param DestX	Lefthand edge of destination
+	 * \param DestY	Top edge of destination
+	 * \param SrcX	Lefthand edge of source
+	 * \param SrcY	Top edge of source
+	 * \param W	Width
+	 * \param H	Height
+	 * \see VIDEO_2DOP_BLIT
+	 */
+	void	(*Blit)(void *Ent, Uint16 DestX, Uint16 DestY, Uint16 SrcX, Uint16 SrcY, Uint16 W, Uint16 H);
+}	tDrvUtil_Video_2DHandlers;
+
+/**
+ * \brief Handle a 2D operation stream for a driver
+ * \param Ent	Value to pass to handlers
+ * \param Buffer	Stream buffer
+ * \param Length	Length of stream
+ * \param Handlers	Handlers to use for the stream
+ * \param SizeofHandlers	Size of \a tDrvUtil_Video_2DHandlers according
+ *        to the driver. Used as version control and error avoidence.
+ */
+extern Uint64	DrvUtil_Video_2DStream(void *Ent, void *Buffer, int Length,
+	tDrvUtil_Video_2DHandlers *Handlers, int SizeofHandlers);
 
 #endif