Kernel/include/tpl_drv_video.h

   1 /**\r
   2  * \file tpl_drv_video.h\r
   3  * \brief Video Driver Interface Definitions\r
   4  * \note For AcessOS Version 1\r
   5  * \r
   6  * Video drivers extend the common driver interface tpl_drv_common.h\r
   7  * and must support _at least_ the IOCtl numbers defined in this file\r
   8  * to be compatable with Acess.\r
   9  * \r
  10  * \section IOCtls\r
  11  * As said, a compatable driver must implement these calls correctly,\r
  12  * but they may choose not to allow direct user access to the framebuffer.\r
  13  * \r
  14  * \section Screen Contents\r
  15  * Writes to the driver's file while in component colour modes\r
  16  * must correspond to a change of the contents of the screen. The framebuffer\r
  17  * must start at offset 0 in the file.\r
  18  * In pallete colour modes the LFB is preceded by a 1024 byte pallete (allowing\r
  19  * room for 256 entries of 32-bits each)\r
  20  * Reading from the screen must either return zero, or read from the\r
  21  * framebuffer.\r
  22  * \r
  23  * \section Mode Support\r
  24  * All video drivers must support at least one text mode (Mode #0)\r
  25  * For each graphics mode the driver exposes, there must be a corresponding\r
  26  * text mode with the same resolution, this mode will be used when the\r
  27  * user switches to a text Virtual Terminal while in graphics mode.\r
  28  */\r
  29 #ifndef _TPL_VIDEO_H\r
  30 #define _TPL_VIDEO_H\r
  31 \r
  32 #include <tpl_drv_common.h>\r
  33 \r
  34 /**\r
  35  * \enum eTplVideo_IOCtl\r
  36  * \brief Common Video IOCtl Calls\r
  37  * \extends eTplDrv_IOCtl\r
  38  */\r
  39 enum eTplVideo_IOCtl {\r
  40         /**\r
  41          * ioctl(..., int *mode)\r
  42          * \brief Get/Set Mode\r
  43          * \return Current mode ID or -1 on error\r
  44          * \r
  45          * If \a mode is non-NULL, the current video mode is set to \a *mode.\r
  46          * This updated ID is then returned to the user.\r
  47          */\r
  48         VIDEO_IOCTL_GETSETMODE = 4,\r
  49         \r
  50         /**\r
  51          * ioctl(..., tVideo_IOCtl_Mode *info)\r
  52          * \brief Find a matching mode\r
  53          * \return 1 if a mode was found, 0 otherwise\r
  54          * \r
  55          * Using avaliable modes matching the \a bpp and \a flags fields\r
  56          * set the \a id field to the mode id of the mode with the closest\r
  57          * \a width and \a height.\r
  58          */\r
  59         VIDEO_IOCTL_FINDMODE,\r
  60         \r
  61         /**\r
  62          * ioctl(..., tVideo_IOCtl_Mode *info)\r
  63          * \brief Get mode info\r
  64          * \return 1 if the mode exists, 0 otherwise\r
  65          * \r
  66          * Set \a info's fields to the mode specified by the \a id field.\r
  67          */\r
  68         VIDEO_IOCTL_MODEINFO,\r
  69         \r
  70         /**\r
  71          * ioctl(..., int *NewFormat)\r
  72          * \brief Switches between Text, Framebuffer and 3D modes\r
  73          * \param NewFormat     Pointer to the new format code (see eTplVideo_BufFormats)\r
  74          * \return Original format\r
  75          * \r
  76          * Enabes and disables the video text mode, changing the behavior of\r
  77          * writes to the device file.\r
  78          */\r
  79         VIDEO_IOCTL_SETBUFFORMAT,\r
  80         \r
  81         /**\r
  82          * ioctl(..., tVideo_IOCtl_Pos *pos)\r
  83          * \brief Sets the cursor position\r
  84          * \return Boolean success\r
  85          * \r
  86          * Set the text mode cursor position (if it is supported)\r
  87          * If the \a pos is set to (-1,-1) the cursor is hidden, otherwise\r
  88          * \a pos MUST be within the current screen size (as given by the\r
  89          * current mode's tVideo_IOCtl_Mode.width and tVideo_IOCtl_Mode.height\r
  90          * fields).\r
  91          */\r
  92         VIDEO_IOCTL_SETCURSOR,\r
  93         \r
  94         /**\r
  95          * ioctl(..., tVAddr MapTo)\r
  96          * \brief Request access to Framebuffer\r
  97          * \return Boolean Success\r
  98          * \r
  99          * Requests the driver to allow the user direct access to the\r
 100          * framebuffer by mapping it to the supplied address.\r
 101          * If the driver does not allow this boolean FALSE (0) is returned,\r
 102          * else if the call succeeds (and the framebuffer ends up mapped) boolean\r
 103          * TRUE (1) is returned.\r
 104          */\r
 105         VIDEO_IOCTL_REQLFB\r
 106 };\r
 107 \r
 108 /**\r
 109  * \brief Mode Structure used in IOCtl Calls\r
 110  * \r
 111  * Defines a video mode supported by (or requested of) this driver (depending\r
 112  * on what ioctl call is used)\r
 113  */\r
 114 typedef struct sVideo_IOCtl_Mode\r
 115 {\r
 116         short   id;             //!< Mode ID\r
 117         Uint16  width;  //!< Width\r
 118         Uint16  height; //!< Height\r
 119         Uint8   bpp;    //!< Bits per Unit (Character or Pixel, depending on \a flags)\r
 120         Uint8   flags;  //!< Mode Flags\r
 121 }       tVideo_IOCtl_Mode;\r
 122 \r
 123 /**\r
 124  * \brief Buffer Format Codes\r
 125  */\r
 126 enum eTplVideo_BufFormats\r
 127 {\r
 128         /**\r
 129          * \brief Text Mode\r
 130          * \r
 131          * The device file presents itself as an array of ::tVT_Char\r
 132          * each describing a character cell on the screen.\r
 133          * These cells are each \a giVT_CharWidth pixels wide and\r
 134          * \a giVT_CharHeight high.\r
 135          */\r
 136         VIDEO_BUFFMT_TEXT,\r
 137         /**\r
 138          * \brief Framebuffer Mode\r
 139          * \r
 140          * The device file presents as an array of 32-bpp pixels describing\r
 141          * the entire screen. The format of a single pixel is in xRGB format\r
 142          * (top 8 bits ignored, next 8 bits red, next 8 bits green and\r
 143          * the bottom 8 bits blue)\r
 144          */\r
 145         VIDEO_BUFFMT_FRAMEBUFFER,\r
 146         /**\r
 147          * \brief 2D Accelerated Mode\r
 148          * \r
 149          * The device file acts as a character device, accepting a stream of\r
 150          * commands described in eTplVideo_2DCommands when written to.\r
 151          */\r
 152         VIDEO_BUFFMT_2DSTREAM,\r
 153         /**\r
 154          * \brief 3D Accelerated Mode\r
 155          * \r
 156          * The device file acts as a character device, accepting a stream of\r
 157          * commands described in eTplVideo_3DCommands when written to.\r
 158          */\r
 159         VIDEO_BUFFMT_3DSTREAM\r
 160 };\r
 161 \r
 162 /**\r
 163  * \brief 2D Accellerated Video Commands\r
 164  * \r
 165  * Commands passed in the command stream for ::VIDEO_BUFFMT_2DSTREAM\r
 166  */\r
 167 enum eTplVideo_2DCommands\r
 168 {\r
 169         /**\r
 170          * \brief No Operation\r
 171          */\r
 172         VIDEO_2DOP_NOP,\r
 173         /**\r
 174          * \brief Fill a region\r
 175          * \param X     Uint16 - Leftmost pixels of the region\r
 176          * \param Y     Uint16 - Topmost pixels of the region\r
 177          * \param W     Uint16 - Width of the region\r
 178          * \param H     Uint16 - Height of the region\r
 179          * \param Colour        Uint32 - Value to fill with\r
 180          */\r
 181         VIDEO_2DOP_FILL,\r
 182         /**\r
 183          * \brief Copy a region from one part of the framebuffer to another\r
 184          * \param DestX Uint16 - Leftmost pixels of the destination\r
 185          * \param DestY Uint16 - Topmost pixels of the destination\r
 186          * \param SrcX  Uint16 - Leftmost pixels of the source\r
 187          * \param SrcY  Uint16 - Topmost pixels of the source\r
 188          * \param Width Uint16 - Width of the region\r
 189          * \param Height        Uint16 - Height of the region\r
 190          */\r
 191         VIDEO_2DOP_BLIT,\r
 192 \r
 193         NUM_VIDEO_2DOPS\r
 194 };\r
 195 \r
 196 /**\r
 197  * \brief Describes a position in the video framebuffer\r
 198  */\r
 199 typedef struct sVideo_IOCtl_Pos\r
 200 {\r
 201         Sint16  x;      //!< X Coordinate\r
 202         Sint16  y;      //!< Y Coordinate\r
 203 }       tVideo_IOCtl_Pos;\r
 204 \r
 205 /**\r
 206  * \brief Virtual Terminal Representation of a character\r
 207  */\r
 208 typedef struct sVT_Char\r
 209 {\r
 210         Uint32  Ch;     //!< UTF-32 Character\r
 211         union {\r
 212                 struct {\r
 213                         Uint16  BGCol;  //!< 12-bit Foreground Colour\r
 214                         Uint16  FGCol;  //!< 12-bit Background Colour\r
 215                 };\r
 216                 Uint32  Colour; //!< Compound colour for ease of access\r
 217         };\r
 218 }       tVT_Char;\r
 219 \r
 220 /**\r
 221  * \name Basic builtin colour definitions\r
 222  * \{\r
 223  */\r
 224 #define VT_COL_BLACK    0x0000\r
 225 #define VT_COL_GREY             0x0888\r
 226 #define VT_COL_LTGREY   0x0CCC\r
 227 #define VT_COL_WHITE    0x0FFF\r
 228 /**\r
 229  * \}\r
 230  */\r
 231 \r
 232 //! \brief Defines the width of a rendered character\r
 233 extern int      giVT_CharWidth;\r
 234 //! \brief Defines the height of a rendered character\r
 235 extern int      giVT_CharHeight;\r
 236 /**\r
 237  * \fn void VT_Font_Render(Uint32 Codepoint, void *Buffer, int Pitch, Uint32 BGC, Uint32 FGC)\r
 238  * \brief Driver helper that renders a character to a buffer\r
 239  * \param Codepoint     Unicode character to render\r
 240  * \param Buffer        Buffer to render to (32-bpp)\r
 241  * \param Pitch Number of DWords per line\r
 242  * \param BGC   32-bit Background Colour\r
 243  * \param FGC   32-bit Foreground Colour\r
 244  * \r
 245  * This function is provided to help video drivers to support a simple\r
 246  * text mode by keeping the character rendering abstracted from the driver,\r
 247  * easing the driver development and reducing code duplication.\r
 248  */\r
 249 extern void     VT_Font_Render(Uint32 Codepoint, void *Buffer, int Pitch, Uint32 BGC, Uint32 FGC);\r
 250 /**\r
 251  * \fn Uint32 VT_Colour12to24(Uint16 Col12)\r
 252  * \brief Converts a colour from 12bpp to 32bpp\r
 253  * \param Col12 12-bpp input colour\r
 254  * \return Expanded 32-bpp (24-bit colour) version of \a Col12\r
 255  */\r
 256 extern Uint32   VT_Colour12to24(Uint16 Col12);\r
 257 \r
 258 /**\r
 259  * \brief Handlers for eTplVideo_2DCommands\r
 260  */\r
 261 typedef struct sDrvUtil_Video_2DHandlers\r
 262 {\r
 263         /**\r
 264          * \brief No Operation, Ignored\r
 265          * \see VIDEO_2DOP_NOP\r
 266          */\r
 267         void    *Nop;\r
 268         /**\r
 269          * \brief Fill a buffer region\r
 270          * \param X     Lefthand edge\r
 271          * \param Y     Top edge\r
 272          * \param W     Width\r
 273          * \param H     Height\r
 274          * \param Colour        Colour to fill with\r
 275          * \see VIDEO_2DOP_FILL\r
 276          */\r
 277         void    (*Fill)(void *Ent, Uint16 X, Uint16 Y, Uint16 W, Uint16 H, Uint32 Colour);\r
 278         /**\r
 279          * \brief Fill a buffer region\r
 280          * \param DestX Lefthand edge of destination\r
 281          * \param DestY Top edge of destination\r
 282          * \param SrcX  Lefthand edge of source\r
 283          * \param SrcY  Top edge of source\r
 284          * \param W     Width\r
 285          * \param H     Height\r
 286          * \see VIDEO_2DOP_BLIT\r
 287          */\r
 288         void    (*Blit)(void *Ent, Uint16 DestX, Uint16 DestY, Uint16 SrcX, Uint16 SrcY, Uint16 W, Uint16 H);\r
 289 }       tDrvUtil_Video_2DHandlers;\r
 290 \r
 291 /**\r
 292  * \brief Handle a 2D operation stream for a driver\r
 293  * \param Ent   Value to pass to handlers\r
 294  * \param Buffer        Stream buffer\r
 295  * \param Length        Length of stream\r
 296  * \param Handlers      Handlers to use for the stream\r
 297  * \param SizeofHandlers        Size of \a tDrvUtil_Video_2DHandlers according\r
 298  *        to the driver. Used as version control and error avoidence.\r
 299  */\r
 300 extern Uint64   DrvUtil_Video_2DStream(void *Ent, void *Buffer, int Length,\r
 301         tDrvUtil_Video_2DHandlers *Handlers, int SizeofHandlers);\r
 302 \r
 303 #endif\r