Kernel/include/api_drv_video.h

   1 /**\r
   2  * \file api_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 api_drv_common.h\r
   7  * and must support the IOCtl numbers defined in this file to be\r
   8  * compatable with Acess (drivers may implement more IOCtls above\r
   9  * DRV_IOCTL_USERMIN).\r
  10  * \r
  11  * \section IOCtls\r
  12  * As said, a compatable driver must implement these calls correctly,\r
  13  * but they may choose not to allow direct user access to the framebuffer.\r
  14  * \r
  15  * \section Screen Contents\r
  16  * Writes to the driver's file while in component colour modes\r
  17  * must correspond to a change of the contents of the screen. The framebuffer\r
  18  * must start at offset 0 in the file.\r
  19  * Reading from the screen must either return zero, or read from the\r
  20  * framebuffer.\r
  21  * \r
  22  * \section Mode Support\r
  23  * All video drivers must support text output for every resolution (hardware\r
  24  * accelerated or software), and at least the _BLIT and _FILL 2D operations\r
  25  * (these may be implemented specifically for text mode).\r
  26  */\r
  27 #ifndef _API_DRV_VIDEO_H\r
  28 #define _API_DRV_VIDEO_H\r
  29 \r
  30 #include <api_drv_common.h>\r
  31 \r
  32 /**\r
  33  * \enum eTplVideo_IOCtl\r
  34  * \brief Common Video IOCtl Calls\r
  35  * \extends eTplDrv_IOCtl\r
  36  */\r
  37 enum eTplVideo_IOCtl {\r
  38         /**\r
  39          * ioctl(..., int *mode)\r
  40          * \brief Get/Set Mode\r
  41          * \return Current mode ID or -1 on error\r
  42          * \r
  43          * If \a mode is non-NULL, the current video mode is set to \a *mode.\r
  44          * This updated ID is then returned to the user.\r
  45          */\r
  46         VIDEO_IOCTL_GETSETMODE = 4,\r
  47         \r
  48         /**\r
  49          * ioctl(..., tVideo_IOCtl_Mode *info)\r
  50          * \brief Find a matching mode\r
  51          * \return 1 if a mode was found, 0 otherwise\r
  52          * \r
  53          * Using avaliable modes matching the \a bpp and \a flags fields\r
  54          * set the \a id, \a width and \a heights fields to the closest\r
  55          * matching mode.\r
  56          */\r
  57         VIDEO_IOCTL_FINDMODE,\r
  58         \r
  59         /**\r
  60          * ioctl(..., tVideo_IOCtl_Mode *info)\r
  61          * \brief Get mode info\r
  62          * \return 1 if the mode exists, 0 otherwise\r
  63          * \r
  64          * Set \a info's fields to the mode specified by the \a id field.\r
  65          */\r
  66         VIDEO_IOCTL_MODEINFO,\r
  67         \r
  68         /**\r
  69          * ioctl(..., int *NewFormat)\r
  70          * \brief Switches between Text, Framebuffer and 3D modes\r
  71          * \param NewFormat     Pointer to the new format code (see eTplVideo_BufFormats)\r
  72          * \return Original format\r
  73          * \r
  74          * Enabes and disables the video text mode, changing the behavior of\r
  75          * writes to the device file.\r
  76          */\r
  77         VIDEO_IOCTL_SETBUFFORMAT,\r
  78         \r
  79         /**\r
  80          * ioctl(..., tVideo_IOCtl_Pos *pos)\r
  81          * \brief Sets the cursor position\r
  82          * \return Boolean success\r
  83          * \r
  84          * Set the text mode cursor position (if it is supported)\r
  85          * If the \a pos is set to (-1,-1) the cursor is hidden, otherwise\r
  86          * \a pos MUST be within the current screen size (as given by the\r
  87          * current mode's tVideo_IOCtl_Mode.width and tVideo_IOCtl_Mode.height\r
  88          * fields).\r
  89          */\r
  90         VIDEO_IOCTL_SETCURSOR,\r
  91         \r
  92         /**\r
  93          * ioctl(..., tVideo_IOCtl_Bitmap *Image)\r
  94          * \brief Sets the cursor image\r
  95          * \return Boolean success\r
  96          *\r
  97          * Sets the graphics mode cursor image\r
  98          */\r
  99         VIDEO_IOCTL_SETCURSORBITMAP\r
 100 };\r
 101 \r
 102 /**\r
 103  * \brief Symbolic names for Video IOCtls (#4 onwards)\r
 104  */\r
 105 #define DRV_VIDEO_IOCTLNAMES    "getset_mode", "find_mode", "mode_info", "set_buf_format", "set_cursor", "set_cursor_bitmap"\r
 106 \r
 107 /**\r
 108  * \brief Mode Structure used in IOCtl Calls\r
 109  * \r
 110  * Defines a video mode supported by (or requested of) this driver (depending\r
 111  * on what ioctl call is used)\r
 112  */\r
 113 typedef struct sVideo_IOCtl_Mode\r
 114 {\r
 115         short   id;             //!< Mode ID\r
 116         Uint16  width;  //!< Width\r
 117         Uint16  height; //!< Height\r
 118         Uint8   bpp;    //!< Bits per pixel\r
 119         Uint8   flags;  //!< Mode Flags (none defined, should be zero)\r
 120 }       tVideo_IOCtl_Mode;\r
 121 \r
 122 /**\r
 123  * \brief Buffer Format Codes\r
 124  */\r
 125 enum eTplVideo_BufFormats\r
 126 {\r
 127         /**\r
 128          * \brief Text Mode\r
 129          * \r
 130          * The device file presents itself as an array of ::tVT_Char\r
 131          * each describing a character cell on the screen.\r
 132          * These cells are each \a giVT_CharWidth pixels wide and\r
 133          * \a giVT_CharHeight high.\r
 134          */\r
 135         VIDEO_BUFFMT_TEXT,\r
 136         /**\r
 137          * \brief Framebuffer Mode\r
 138          * \r
 139          * The device file presents as an array of 32-bpp pixels describing\r
 140          * the entire screen. The format of a single pixel is in xRGB format\r
 141          * (top 8 bits ignored, next 8 bits red, next 8 bits green and\r
 142          * the bottom 8 bits blue)\r
 143          */\r
 144         VIDEO_BUFFMT_FRAMEBUFFER,\r
 145         /**\r
 146          * \brief 2D Accelerated Mode\r
 147          * \r
 148          * The device file acts as a character device, accepting a stream of\r
 149          * commands described in eTplVideo_2DCommands when written to.\r
 150          */\r
 151         VIDEO_BUFFMT_2DSTREAM,\r
 152         /**\r
 153          * \brief 3D Accelerated Mode\r
 154          * \r
 155          * The device file acts as a character device, accepting a stream of\r
 156          * commands described in eTplVideo_3DCommands when written to.\r
 157          */\r
 158         VIDEO_BUFFMT_3DSTREAM\r
 159 };\r
 160 \r
 161 /**\r
 162  * \brief 2D Accellerated Video Commands\r
 163  * \r
 164  * Commands passed in the command stream for ::VIDEO_BUFFMT_2DSTREAM\r
 165  */\r
 166 enum eTplVideo_2DCommands\r
 167 {\r
 168         /**\r
 169          * \brief No Operation\r
 170          */\r
 171         VIDEO_2DOP_NOP,\r
 172         /**\r
 173          * \brief Fill a region\r
 174          * \param X     Uint16 - Leftmost pixels of the region\r
 175          * \param Y     Uint16 - Topmost pixels of the region\r
 176          * \param W     Uint16 - Width of the region\r
 177          * \param H     Uint16 - Height of the region\r
 178          * \param Colour        Uint32 - Value to fill with\r
 179          */\r
 180         VIDEO_2DOP_FILL,\r
 181         /**\r
 182          * \brief Copy a region from one part of the framebuffer to another\r
 183          * \param DestX Uint16 - Leftmost pixels of the destination\r
 184          * \param DestY Uint16 - Topmost pixels of the destination\r
 185          * \param SrcX  Uint16 - Leftmost pixels of the source\r
 186          * \param SrcY  Uint16 - Topmost pixels of the source\r
 187          * \param Width Uint16 - Width of the region\r
 188          * \param Height        Uint16 - Height of the region\r
 189          */\r
 190         VIDEO_2DOP_BLIT,\r
 191 \r
 192 \r
 193         /**\r
 194          * \brief Copy a region from video memory to the framebuffer\r
 195          */\r
 196         VIDEO_2DOP_BLITBUF,\r
 197 \r
 198         /**\r
 199          * \brief Copy and scale a region from video memory to the framebuffer\r
 200          */\r
 201         VIDEO_2DOP_BLITSCALEBUF,\r
 202 \r
 203         NUM_VIDEO_2DOPS\r
 204 };\r
 205 \r
 206 /**\r
 207  * \brief Describes a position in the video framebuffer\r
 208  */\r
 209 typedef struct sVideo_IOCtl_Pos\r
 210 {\r
 211         Sint16  x;      //!< X Coordinate\r
 212         Sint16  y;      //!< Y Coordinate\r
 213 }       tVideo_IOCtl_Pos;\r
 214 \r
 215 /**\r
 216  * \brief Bitmap object (out of band image)\r
 217  */\r
 218 typedef struct sVideo_IOCtl_Bitmap\r
 219 {\r
 220         Sint16  W;      //!< Width of image\r
 221         Sint16  H;      //!< Height of image\r
 222         Sint16  XOfs;   //!< X Offset of center\r
 223         Sint16  YOfs;   //!< Y Offset of center\r
 224         Uint32  Data[]; //!< Image data (ARGB array)\r
 225 }       tVideo_IOCtl_Bitmap;\r
 226 \r
 227 /**\r
 228  * \brief Virtual Terminal Representation of a character\r
 229  */\r
 230 typedef struct sVT_Char\r
 231 {\r
 232         Uint32  Ch;     //!< UTF-32 Character\r
 233         union {\r
 234                 struct {\r
 235                         Uint16  BGCol;  //!< 12-bit Foreground Colour\r
 236                         Uint16  FGCol;  //!< 12-bit Background Colour\r
 237                 };\r
 238                 Uint32  Colour; //!< Compound colour for ease of access\r
 239         };\r
 240 }       tVT_Char;\r
 241 \r
 242 /**\r
 243  * \name Basic builtin colour definitions\r
 244  * \{\r
 245  */\r
 246 #define VT_COL_BLACK    0x0000\r
 247 #define VT_COL_GREY             0x0888\r
 248 #define VT_COL_LTGREY   0x0CCC\r
 249 #define VT_COL_WHITE    0x0FFF\r
 250 /**\r
 251  * \}\r
 252  */\r
 253 \r
 254 //! \brief Defines the width of a rendered character\r
 255 extern int      giVT_CharWidth;\r
 256 //! \brief Defines the height of a rendered character\r
 257 extern int      giVT_CharHeight;\r
 258 /**\r
 259  * \name Font rendering\r
 260  * \{\r
 261  */\r
 262 /**\r
 263  * \brief Driver helper that renders a character to a buffer\r
 264  * \param Codepoint     Unicode character to render\r
 265  * \param Buffer        Buffer to render to\r
 266  * \param Depth Bit depth of the destination buffer\r
 267  * \param Pitch Number of bytes per line\r
 268  * \param BGC   32-bit Background Colour\r
 269  * \param FGC   32-bit Foreground Colour\r
 270  * \r
 271  * This function is provided to help video drivers to support a simple\r
 272  * text mode by keeping the character rendering abstracted from the driver,\r
 273  * easing the driver development and reducing code duplication.\r
 274  */\r
 275 extern void     VT_Font_Render(Uint32 Codepoint, void *Buffer, int Depth, int Pitch, Uint32 BGC, Uint32 FGC);\r
 276 /**\r
 277  * \fn Uint32 VT_Colour12to24(Uint16 Col12)\r
 278  * \brief Converts a colour from 12bpp to 24bpp\r
 279  * \param Col12 12-bpp input colour\r
 280  * \return Expanded 32-bpp (24-bit colour) version of \a Col12\r
 281  */\r
 282 extern Uint32   VT_Colour12to24(Uint16 Col12);\r
 283 /**\r
 284  * \brief Converts a colour from 12bpp to 14bpp\r
 285  * \param Col12 12-bpp input colour\r
 286  * \return 15 bits per pixel value\r
 287  */\r
 288 extern Uint16   VT_Colour12to15(Uint16 Col12);\r
 289 /**\r
 290  * \brief Converts a colour from 12bpp to 32bpp\r
 291  * \param Col12 12-bpp input colour\r
 292  * \param Depth Desired bit depth\r
 293  * \return \a Depth bit number, denoting Col12\r
 294  * \r
 295  * Expands the source colour into a \a Depth bits per pixel representation.\r
 296  * The colours are expanded with preference to Green, Blue and Red in that order\r
 297  * (so, green gets the first spare pixel, blue gets the next, and red never gets\r
 298  * the spare). \n\r
 299  * The final bit of each component is used to fill the lower bits of the output.\r
 300  */\r
 301 extern Uint32   VT_Colour12toN(Uint16 Col12, int Depth);\r
 302 /**\r
 303  * \}\r
 304  */\r
 305 \r
 306 /**\r
 307  * \brief Maximum cursor width for using the DrvUtil software cursor\r
 308  */\r
 309 #define DRVUTIL_MAX_CURSOR_W    32\r
 310 /**\r
 311  * \brief Maximum cursor width for using the DrvUtil software cursor\r
 312  */\r
 313 #define DRVUTIL_MAX_CURSOR_H    32\r
 314 \r
 315 /**\r
 316  * \brief Framebuffer information used by all DrvUtil_Video functions\r
 317  */\r
 318 typedef struct sDrvUtil_Video_BufInfo\r
 319 {\r
 320         /**\r
 321          * \name Framebuffer state\r
 322          * \{\r
 323          */\r
 324         /**\r
 325          * \brief Framebuffer virtual address\r
 326          */\r
 327         void    *Framebuffer;\r
 328         /**\r
 329          * \brief Bytes between the start of each line\r
 330          */\r
 331          int    Pitch;\r
 332         /**\r
 333          * \brief Number of pixels in each line\r
 334          */\r
 335         short   Width;\r
 336         /**\r
 337          * \brief Total number of lines\r
 338          */\r
 339         short   Height;\r
 340         /**\r
 341          * \brief Bit depth of the framebuffer\r
 342          */\r
 343         short   Depth;\r
 344         /*\r
 345          * \}\r
 346          */\r
 347         \r
 348         /**\r
 349          * \brief Buffer write format\r
 350          */\r
 351         short   BufferFormat;\r
 352         \r
 353         /**\r
 354          * \name Software cursor controls\r
 355          * \{\r
 356          */\r
 357         /**\r
 358          * \brief X coordinate of the cursor\r
 359          */\r
 360         short   CursorX;\r
 361         /**\r
 362          * \brief Y coordinate of the cursor\r
 363          */\r
 364         short   CursorY;\r
 365 \r
 366         /**\r
 367          * \brief Cursor bitmap\r
 368          */\r
 369         tVideo_IOCtl_Bitmap     *CursorBitmap;\r
 370         /*\r
 371          * \}\r
 372          */\r
 373 \r
 374         /*\r
 375          * \name Internal fields\r
 376          * \{\r
 377          */\r
 378 \r
 379         /**\r
 380          * \brief Buffer to store the area under the cursor\r
 381          */\r
 382         void    *CursorSaveBuf;\r
 383         \r
 384          int    CursorReadX;    //!< X offset in cursor bitmap corresponding to \a CursorDestX\r
 385          int    CursorReadY;    //!< Same as \a CursorReadX but for Y\r
 386          int    CursorRenderW;  //!< Width of rendered cursor\r
 387          int    CursorRenderH;  //!< Height of rendered cursor\r
 388          int    CursorDestX;    //!< X coordinate Destination for rendered cursor\r
 389          int    CursorDestY;    //!< Y coordinate destination for rendered cursor\r
 390 \r
 391         /*\r
 392          * \}\r
 393          */\r
 394 } tDrvUtil_Video_BufInfo;\r
 395 \r
 396 /**\r
 397  * \brief Handlers for eTplVideo_2DCommands\r
 398  */\r
 399 typedef struct sDrvUtil_Video_2DHandlers\r
 400 {\r
 401         /**\r
 402          * \brief No Operation, Ignored\r
 403          * \see VIDEO_2DOP_NOP\r
 404          */\r
 405         void    *Nop;\r
 406         /**\r
 407          * \brief Fill a buffer region\r
 408          * \param X     Lefthand edge\r
 409          * \param Y     Top edge\r
 410          * \param W     Width\r
 411          * \param H     Height\r
 412          * \param Colour        Colour to fill with\r
 413          * \see VIDEO_2DOP_FILL\r
 414          */\r
 415         void    (*Fill)(void *Ent, Uint16 X, Uint16 Y, Uint16 W, Uint16 H, Uint32 Colour);\r
 416         /**\r
 417          * \brief Fill a buffer region\r
 418          * \param DestX Lefthand edge of destination\r
 419          * \param DestY Top edge of destination\r
 420          * \param SrcX  Lefthand edge of source\r
 421          * \param SrcY  Top edge of source\r
 422          * \param W     Width\r
 423          * \param H     Height\r
 424          * \see VIDEO_2DOP_BLIT\r
 425          */\r
 426         void    (*Blit)(void *Ent, Uint16 DestX, Uint16 DestY, Uint16 SrcX, Uint16 SrcY, Uint16 W, Uint16 H);\r
 427 } tDrvUtil_Video_2DHandlers;\r
 428 \r
 429 /**\r
 430  * \brief Handle a 2D operation stream for a driver\r
 431  * \param Ent   Value to pass to handlers\r
 432  * \param Buffer        Stream buffer\r
 433  * \param Length        Length of stream\r
 434  * \param Handlers      Handlers to use for the stream\r
 435  * \param SizeofHandlers        Size of \a tDrvUtil_Video_2DHandlers according\r
 436  *        to the driver. Used as version control and error avoidence.\r
 437  */\r
 438 extern int      DrvUtil_Video_2DStream(void *Ent, void *Buffer, int Length,\r
 439         tDrvUtil_Video_2DHandlers *Handlers, int SizeofHandlers);\r
 440 \r
 441 /**\r
 442  * \brief Perform write operations to a LFB\r
 443  * \param FBInfo        Framebuffer descriptor, see type for details\r
 444  * \param Offset        Offset provided by VFS call\r
 445  * \param Length        Length provided by VFS call\r
 446  * \param Src   Data from VFS call\r
 447  * \return Number of bytes written\r
 448  *\r
 449  * Handles all write modes in software, using the VT font calls for rendering.\r
 450  * \note Calls the cursor clear and redraw if the cursor area is touched\r
 451  */\r
 452 extern int      DrvUtil_Video_WriteLFB(tDrvUtil_Video_BufInfo *FBInfo, size_t Offset, size_t Length, void *Src);\r
 453 \r
 454 /**\r
 455  * \name Software cursor rendering\r
 456  * \{\r
 457  */\r
 458 /**\r
 459  * \brief Set the cursor bitmap for a buffer\r
 460  * \param Buf   Framebuffer descriptor\r
 461  * \param Bitmap        New cursor bitmap\r
 462  */\r
 463 extern int      DrvUtil_Video_SetCursor(tDrvUtil_Video_BufInfo *Buf, tVideo_IOCtl_Bitmap *Bitmap);\r
 464 /**\r
 465  * \brief Render the cursor at (\a X, \a Y)\r
 466  * \param Buf   Framebuffer descriptor, see type for details\r
 467  * \param X     X coord of the cursor\r
 468  * \param Y     Y coord of the cursor\r
 469  */\r
 470 extern void     DrvUtil_Video_DrawCursor(tDrvUtil_Video_BufInfo *Buf, int X, int Y);\r
 471 /**\r
 472  * \brief Removes the rendered cursor from the screen\r
 473  * \param Buf   Framebuffer descriptor, see type for details\r
 474  */\r
 475 extern void     DrvUtil_Video_RemoveCursor(tDrvUtil_Video_BufInfo *Buf);\r
 476 \r
 477 /**\r
 478  * \brief Text mode cursor image\r
 479  */\r
 480 extern tVideo_IOCtl_Bitmap     gDrvUtil_TextModeCursor;\r
 481 /**\r
 482  * \}\r
 483  */\r
 484 #endif\r