Kernel - (minor) Debug changes in x86_64
[tpg/acess2.git] / KernelLand / 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          * \brief Cached copy of the screens state (only used if not NULL)\r
346          */\r
347         void    *BackBuffer;\r
348         /*\r
349          * \}\r
350          */\r
351         \r
352         /**\r
353          * \brief Buffer write format\r
354          */\r
355         short   BufferFormat;\r
356         \r
357         /**\r
358          * \name Software cursor controls\r
359          * \{\r
360          */\r
361         /**\r
362          * \brief X coordinate of the cursor\r
363          */\r
364         short   CursorX;\r
365         /**\r
366          * \brief Y coordinate of the cursor\r
367          */\r
368         short   CursorY;\r
369 \r
370         /**\r
371          * \brief Cursor bitmap\r
372          */\r
373         tVideo_IOCtl_Bitmap     *CursorBitmap;\r
374         /*\r
375          * \}\r
376          */\r
377 \r
378         /*\r
379          * \name Internal fields\r
380          * \{\r
381          */\r
382 \r
383         /**\r
384          * \brief Buffer to store the area under the cursor\r
385          */\r
386         void    *CursorSaveBuf;\r
387         \r
388          int    CursorReadX;    //!< X offset in cursor bitmap corresponding to \a CursorDestX\r
389          int    CursorReadY;    //!< Same as \a CursorReadX but for Y\r
390          int    CursorRenderW;  //!< Width of rendered cursor\r
391          int    CursorRenderH;  //!< Height of rendered cursor\r
392          int    CursorDestX;    //!< X coordinate Destination for rendered cursor\r
393          int    CursorDestY;    //!< Y coordinate destination for rendered cursor\r
394 \r
395         /*\r
396          * \}\r
397          */\r
398 } tDrvUtil_Video_BufInfo;\r
399 \r
400 /**\r
401  * \brief Handlers for eTplVideo_2DCommands\r
402  */\r
403 typedef struct sDrvUtil_Video_2DHandlers\r
404 {\r
405         /**\r
406          * \brief No Operation, Ignored\r
407          * \see VIDEO_2DOP_NOP\r
408          */\r
409         void    *Nop;\r
410         /**\r
411          * \brief Fill a buffer region\r
412          * \param X     Lefthand edge\r
413          * \param Y     Top edge\r
414          * \param W     Width\r
415          * \param H     Height\r
416          * \param Colour        Colour to fill with\r
417          * \see VIDEO_2DOP_FILL\r
418          */\r
419         void    (*Fill)(void *Ent, Uint16 X, Uint16 Y, Uint16 W, Uint16 H, Uint32 Colour);\r
420         /**\r
421          * \brief Fill a buffer region\r
422          * \param DestX Lefthand edge of destination\r
423          * \param DestY Top edge of destination\r
424          * \param SrcX  Lefthand edge of source\r
425          * \param SrcY  Top edge of source\r
426          * \param W     Width\r
427          * \param H     Height\r
428          * \see VIDEO_2DOP_BLIT\r
429          */\r
430         void    (*Blit)(void *Ent, Uint16 DestX, Uint16 DestY, Uint16 SrcX, Uint16 SrcY, Uint16 W, Uint16 H);\r
431 } tDrvUtil_Video_2DHandlers;\r
432 \r
433 /**\r
434  * \brief Handle a 2D operation stream for a driver\r
435  * \param Ent   Value to pass to handlers\r
436  * \param Buffer        Stream buffer\r
437  * \param Length        Length of stream\r
438  * \param Handlers      Handlers to use for the stream\r
439  * \param SizeofHandlers        Size of \a tDrvUtil_Video_2DHandlers according\r
440  *        to the driver. Used as version control and error avoidence.\r
441  */\r
442 extern int      DrvUtil_Video_2DStream(void *Ent, const void *Buffer, int Length,\r
443         tDrvUtil_Video_2DHandlers *Handlers, int SizeofHandlers);\r
444 \r
445 /**\r
446  * \brief Perform write operations to a LFB\r
447  * \param FBInfo        Framebuffer descriptor, see type for details\r
448  * \param Offset        Offset provided by VFS call\r
449  * \param Length        Length provided by VFS call\r
450  * \param Src   Data from VFS call\r
451  * \return Number of bytes written\r
452  *\r
453  * Handles all write modes in software, using the VT font calls for rendering.\r
454  * \note Calls the cursor clear and redraw if the cursor area is touched\r
455  */\r
456 extern int      DrvUtil_Video_WriteLFB(tDrvUtil_Video_BufInfo *FBInfo, size_t Offset, size_t Length, const void *Src);\r
457 \r
458 /**\r
459  * \name Software cursor rendering\r
460  * \{\r
461  */\r
462 /**\r
463  * \brief Set the cursor bitmap for a buffer\r
464  * \param Buf   Framebuffer descriptor\r
465  * \param Bitmap        New cursor bitmap\r
466  */\r
467 extern int      DrvUtil_Video_SetCursor(tDrvUtil_Video_BufInfo *Buf, tVideo_IOCtl_Bitmap *Bitmap);\r
468 /**\r
469  * \brief Render the cursor at (\a X, \a Y)\r
470  * \param Buf   Framebuffer descriptor, see type for details\r
471  * \param X     X coord of the cursor\r
472  * \param Y     Y coord of the cursor\r
473  */\r
474 extern void     DrvUtil_Video_DrawCursor(tDrvUtil_Video_BufInfo *Buf, int X, int Y);\r
475 /**\r
476  * \brief Removes the rendered cursor from the screen\r
477  * \param Buf   Framebuffer descriptor, see type for details\r
478  */\r
479 extern void     DrvUtil_Video_RemoveCursor(tDrvUtil_Video_BufInfo *Buf);\r
480 \r
481 /**\r
482  * \brief Text mode cursor image\r
483  */\r
484 extern tVideo_IOCtl_Bitmap     gDrvUtil_TextModeCursor;\r
485 /**\r
486  * \}\r
487  */\r
488 #endif\r

UCC git Repository :: git.ucc.asn.au