+/**\r
+ * \file api_drv_video.h\r
+ * \brief Video Driver Interface Definitions\r
+ * \note For AcessOS Version 1\r
+ * \r
+ * Video drivers extend the common driver interface api_drv_common.h\r
+ * and must support _at least_ the IOCtl numbers defined in this file\r
+ * to be compatable with Acess.\r
+ * \r
+ * \section IOCtls\r
+ * As said, a compatable driver must implement these calls correctly,\r
+ * but they may choose not to allow direct user access to the framebuffer.\r
+ * \r
+ * \section Screen Contents\r
+ * Writes to the driver's file while in component colour modes\r
+ * must correspond to a change of the contents of the screen. The framebuffer\r
+ * must start at offset 0 in the file.\r
+ * Reading from the screen must either return zero, or read from the\r
+ * framebuffer.\r
+ * \r
+ * \section Mode Support\r
+ * All video drivers must support at least one text mode (Mode #0)\r
+ * For each graphics mode the driver exposes, there must be a corresponding\r
+ * text mode with the same resolution, this mode will be used when the\r
+ * user switches to a text Virtual Terminal while in graphics mode.\r
+ */\r
+#ifndef _API_DRV_VIDEO_H\r
+#define _API_DRV_VIDEO_H\r
+\r
+#include <api_drv_common.h>\r
+\r
+/**\r
+ * \enum eTplVideo_IOCtl\r
+ * \brief Common Video IOCtl Calls\r
+ * \extends eTplDrv_IOCtl\r
+ */\r
+enum eTplVideo_IOCtl {\r
+ /**\r
+ * ioctl(..., int *mode)\r
+ * \brief Get/Set Mode\r
+ * \return Current mode ID or -1 on error\r
+ * \r
+ * If \a mode is non-NULL, the current video mode is set to \a *mode.\r
+ * This updated ID is then returned to the user.\r
+ */\r
+ VIDEO_IOCTL_GETSETMODE = 4,\r
+ \r
+ /**\r
+ * ioctl(..., tVideo_IOCtl_Mode *info)\r
+ * \brief Find a matching mode\r
+ * \return 1 if a mode was found, 0 otherwise\r
+ * \r
+ * Using avaliable modes matching the \a bpp and \a flags fields\r
+ * set the \a id field to the mode id of the mode with the closest\r
+ * \a width and \a height.\r
+ */\r
+ VIDEO_IOCTL_FINDMODE,\r
+ \r
+ /**\r
+ * ioctl(..., tVideo_IOCtl_Mode *info)\r
+ * \brief Get mode info\r
+ * \return 1 if the mode exists, 0 otherwise\r
+ * \r
+ * Set \a info's fields to the mode specified by the \a id field.\r
+ */\r
+ VIDEO_IOCTL_MODEINFO,\r
+ \r
+ /**\r
+ * ioctl(..., int *NewFormat)\r
+ * \brief Switches between Text, Framebuffer and 3D modes\r
+ * \param NewFormat Pointer to the new format code (see eTplVideo_BufFormats)\r
+ * \return Original format\r
+ * \r
+ * Enabes and disables the video text mode, changing the behavior of\r
+ * writes to the device file.\r
+ */\r
+ VIDEO_IOCTL_SETBUFFORMAT,\r
+ \r
+ /**\r
+ * ioctl(..., tVideo_IOCtl_Pos *pos)\r
+ * \brief Sets the cursor position\r
+ * \return Boolean success\r
+ * \r
+ * Set the text mode cursor position (if it is supported)\r
+ * If the \a pos is set to (-1,-1) the cursor is hidden, otherwise\r
+ * \a pos MUST be within the current screen size (as given by the\r
+ * current mode's tVideo_IOCtl_Mode.width and tVideo_IOCtl_Mode.height\r
+ * fields).\r
+ */\r
+ VIDEO_IOCTL_SETCURSOR,\r
+ \r
+ /**\r
+ * ioctl(..., tVideo_IOCtl_Bitmap *Image)\r
+ * \brief Sets the cursor image\r
+ * \return Boolean success\r
+ *\r
+ * Sets the graphics mode cursor image\r
+ */\r
+ VIDEO_IOCTL_SETCURSORBITMAP\r
+};\r
+#define DRV_VIDEO_IOCTLNAMES "getset_mode", "find+mode", "mode_info", "set_buf_format", "set_cursor", "set_cursor_bitmap"\r
+\r
+/**\r
+ * \brief Mode Structure used in IOCtl Calls\r
+ * \r
+ * Defines a video mode supported by (or requested of) this driver (depending\r
+ * on what ioctl call is used)\r
+ */\r
+typedef struct sVideo_IOCtl_Mode\r
+{\r
+ short id; //!< Mode ID\r
+ Uint16 width; //!< Width\r
+ Uint16 height; //!< Height\r
+ Uint8 bpp; //!< Bits per Unit (Character or Pixel, depending on \a flags)\r
+ Uint8 flags; //!< Mode Flags\r
+} tVideo_IOCtl_Mode;\r
+\r
+/**\r
+ * \brief Buffer Format Codes\r
+ */\r
+enum eTplVideo_BufFormats\r
+{\r
+ /**\r
+ * \brief Text Mode\r
+ * \r
+ * The device file presents itself as an array of ::tVT_Char\r
+ * each describing a character cell on the screen.\r
+ * These cells are each \a giVT_CharWidth pixels wide and\r
+ * \a giVT_CharHeight high.\r
+ */\r
+ VIDEO_BUFFMT_TEXT,\r
+ /**\r
+ * \brief Framebuffer Mode\r
+ * \r
+ * The device file presents as an array of 32-bpp pixels describing\r
+ * the entire screen. The format of a single pixel is in xRGB format\r
+ * (top 8 bits ignored, next 8 bits red, next 8 bits green and\r
+ * the bottom 8 bits blue)\r
+ */\r
+ VIDEO_BUFFMT_FRAMEBUFFER,\r
+ /**\r
+ * \brief 2D Accelerated Mode\r
+ * \r
+ * The device file acts as a character device, accepting a stream of\r
+ * commands described in eTplVideo_2DCommands when written to.\r
+ */\r
+ VIDEO_BUFFMT_2DSTREAM,\r
+ /**\r
+ * \brief 3D Accelerated Mode\r
+ * \r
+ * The device file acts as a character device, accepting a stream of\r
+ * commands described in eTplVideo_3DCommands when written to.\r
+ */\r
+ VIDEO_BUFFMT_3DSTREAM\r
+};\r
+\r
+/**\r
+ * \brief 2D Accellerated Video Commands\r
+ * \r
+ * Commands passed in the command stream for ::VIDEO_BUFFMT_2DSTREAM\r
+ */\r
+enum eTplVideo_2DCommands\r
+{\r
+ /**\r
+ * \brief No Operation\r
+ */\r
+ VIDEO_2DOP_NOP,\r
+ /**\r
+ * \brief Fill a region\r
+ * \param X Uint16 - Leftmost pixels of the region\r
+ * \param Y Uint16 - Topmost pixels of the region\r
+ * \param W Uint16 - Width of the region\r
+ * \param H Uint16 - Height of the region\r
+ * \param Colour Uint32 - Value to fill with\r
+ */\r
+ VIDEO_2DOP_FILL,\r
+ /**\r
+ * \brief Copy a region from one part of the framebuffer to another\r
+ * \param DestX Uint16 - Leftmost pixels of the destination\r
+ * \param DestY Uint16 - Topmost pixels of the destination\r
+ * \param SrcX Uint16 - Leftmost pixels of the source\r
+ * \param SrcY Uint16 - Topmost pixels of the source\r
+ * \param Width Uint16 - Width of the region\r
+ * \param Height Uint16 - Height of the region\r
+ */\r
+ VIDEO_2DOP_BLIT,\r
+\r
+\r
+ /**\r
+ * \brief Copy a region from video memory to the framebuffer\r
+ */\r
+ VIDEO_2DOP_BLITBUF,\r
+\r
+ /**\r
+ * \brief Copy and scale a region from video memory to the framebuffer\r
+ */\r
+ VIDEO_2DOP_BLITSCALEBUF,\r
+\r
+ NUM_VIDEO_2DOPS\r
+};\r
+\r
+/**\r
+ * \brief Describes a position in the video framebuffer\r
+ */\r
+typedef struct sVideo_IOCtl_Pos\r
+{\r
+ Sint16 x; //!< X Coordinate\r
+ Sint16 y; //!< Y Coordinate\r
+} tVideo_IOCtl_Pos;\r
+\r
+/**\r
+ * \brief Bitmap object (out of band image)\r
+ */\r
+typedef struct sVideo_IOCtl_Bitmap\r
+{\r
+ Sint16 W; //!< Width of image\r
+ Sint16 H; //!< Height of image\r
+ Sint16 XOfs; //!< X Offset of center\r
+ Sint16 YOfs; //!< Y Offset of center\r
+ Uint32 Data[]; //!< Image data (ARGB array)\r
+} tVideo_IOCtl_Bitmap;\r
+\r
+/**\r
+ * \brief Virtual Terminal Representation of a character\r
+ */\r
+typedef struct sVT_Char\r
+{\r
+ Uint32 Ch; //!< UTF-32 Character\r
+ union {\r
+ struct {\r
+ Uint16 BGCol; //!< 12-bit Foreground Colour\r
+ Uint16 FGCol; //!< 12-bit Background Colour\r
+ };\r
+ Uint32 Colour; //!< Compound colour for ease of access\r
+ };\r
+} tVT_Char;\r
+\r
+/**\r
+ * \name Basic builtin colour definitions\r
+ * \{\r
+ */\r
+#define VT_COL_BLACK 0x0000\r
+#define VT_COL_GREY 0x0888\r
+#define VT_COL_LTGREY 0x0CCC\r
+#define VT_COL_WHITE 0x0FFF\r
+/**\r
+ * \}\r
+ */\r
+\r
+//! \brief Defines the width of a rendered character\r
+extern int giVT_CharWidth;\r
+//! \brief Defines the height of a rendered character\r
+extern int giVT_CharHeight;\r
+/**\r
+ * \brief Driver helper that renders a character to a buffer\r
+ * \param Codepoint Unicode character to render\r
+ * \param Buffer Buffer to render to\r
+ * \param Depth Bit depth of the destination buffer\r
+ * \param Pitch Number of bytes per line\r
+ * \param BGC 32-bit Background Colour\r
+ * \param FGC 32-bit Foreground Colour\r
+ * \r
+ * This function is provided to help video drivers to support a simple\r
+ * text mode by keeping the character rendering abstracted from the driver,\r
+ * easing the driver development and reducing code duplication.\r
+ */\r
+extern void VT_Font_Render(Uint32 Codepoint, void *Buffer, int Depth, int Pitch, Uint32 BGC, Uint32 FGC);\r
+/**\r
+ * \fn Uint32 VT_Colour12to24(Uint16 Col12)\r
+ * \brief Converts a colour from 12bpp to 24bpp\r
+ * \param Col12 12-bpp input colour\r
+ * \return Expanded 32-bpp (24-bit colour) version of \a Col12\r
+ */\r
+extern Uint32 VT_Colour12to24(Uint16 Col12);\r
+/**\r
+ * \brief Converts a colour from 12bpp to 14bpp\r
+ * \param Col12 12-bpp input colour\r
+ * \return 15 bits per pixel value\r
+ */\r
+extern Uint16 VT_Colour12to15(Uint16 Col12);\r
+/**\r
+ * \brief Converts a colour from 12bpp to 32bpp\r
+ * \param Col12 12-bpp input colour\r
+ * \param Depth Desired bit depth\r
+ * \return \a Depth bit number, denoting Col12\r
+ * \r
+ * Expands the source colour into a \a Depth bits per pixel representation.\r
+ * The colours are expanded with preference to Green, Blue and Red in that order\r
+ * (so, green gets the first spare pixel, blue gets the next, and red never gets\r
+ * the spare). \n\r
+ * The final bit of each component is used to fill the lower bits of the output.\r
+ */\r
+extern Uint32 VT_Colour12toN(Uint16 Col12, int Depth);\r
+\r
+/**\r
+ * \brief Handlers for eTplVideo_2DCommands\r
+ */\r
+typedef struct sDrvUtil_Video_2DHandlers\r
+{\r
+ /**\r
+ * \brief No Operation, Ignored\r
+ * \see VIDEO_2DOP_NOP\r
+ */\r
+ void *Nop;\r
+ /**\r
+ * \brief Fill a buffer region\r
+ * \param X Lefthand edge\r
+ * \param Y Top edge\r
+ * \param W Width\r
+ * \param H Height\r
+ * \param Colour Colour to fill with\r
+ * \see VIDEO_2DOP_FILL\r
+ */\r
+ void (*Fill)(void *Ent, Uint16 X, Uint16 Y, Uint16 W, Uint16 H, Uint32 Colour);\r
+ /**\r
+ * \brief Fill a buffer region\r
+ * \param DestX Lefthand edge of destination\r
+ * \param DestY Top edge of destination\r
+ * \param SrcX Lefthand edge of source\r
+ * \param SrcY Top edge of source\r
+ * \param W Width\r
+ * \param H Height\r
+ * \see VIDEO_2DOP_BLIT\r
+ */\r
+ void (*Blit)(void *Ent, Uint16 DestX, Uint16 DestY, Uint16 SrcX, Uint16 SrcY, Uint16 W, Uint16 H);\r
+} tDrvUtil_Video_2DHandlers;\r
+\r
+/**\r
+ * \brief Handle a 2D operation stream for a driver\r
+ * \param Ent Value to pass to handlers\r
+ * \param Buffer Stream buffer\r
+ * \param Length Length of stream\r
+ * \param Handlers Handlers to use for the stream\r
+ * \param SizeofHandlers Size of \a tDrvUtil_Video_2DHandlers according\r
+ * to the driver. Used as version control and error avoidence.\r
+ */\r
+extern Uint64 DrvUtil_Video_2DStream(void *Ent, void *Buffer, int Length,\r
+ tDrvUtil_Video_2DHandlers *Handlers, int SizeofHandlers);\r
+\r
+#endif\r