home *** CD-ROM | disk | FTP | other *** search
/ Virtual Reality Zone / VRZONE.ISO / mac / PC / PCGLOVE / GLOVE / OBJGLV.ZIP / DOC / VDRIVERS.DOC < prev    next >
Text File  |  1992-09-25  |  8KB  |  200 lines
  1.  
  2.                     REND386 VIDEO DRIVER CREATION
  3.                Written by Dave Stampe, September 1992
  4.  
  5. Video drivers are compiled in pseudo-tiny mode (code, data in one
  6. segment, stack not assumed in the same segment).  The interface is through
  7. an assembly routine linked to REND386, and through a call table at the start
  8. of the driver.
  9.  
  10. During development, the call module (vdrinte.asm) may be left out of the
  11. REND386 link, and the video driver code itself linked in.  At this stage,
  12. all assembly modules should use the .MODEL LARGE directive.
  13.  
  14. See the file MEMMODEL for a description of the memory modes, and how to
  15. compile your driver.
  16.  
  17. -------------------------------
  18.  
  19. FUNCTIONS TO BE SUPPORTED BY VIDEO DRIVER:
  20. Note all the FAR attributes of the prototypes: VERY IMPORTANT.
  21. ----
  22. struct Screeninfo {
  23.     int xmin, ymin, xmax, ymax, xcent, ycent, colors, pages, bw;
  24.     char id[80];
  25.     };
  26.  
  27. struct Screeninfo far * far screen_data();
  28.  
  29. This is usually the first call made by REND386 to the driver, and it should
  30. return a far pointer to a Screeninfo structure inside the driver.  Most of
  31. the attributes in the structure are self-explanatory.  "bw" is 0 if a color
  32. palette is to be used, 1 if a monochrome palette is preferred.
  33. ----
  34. void far set_gmode(int arg);       /* enters graphics, clears screen */
  35. void far exit_gmode();             /* exits to text mode */
  36.  
  37. These functions are self-explanetory.  If you have multiple video
  38. sources for a HMD, this should initialize all sources in one call.
  39. set_gmode() may be passed a single parameter to, for example, set
  40. the video mode on a SVGA card from the .cfg file.
  41. ----
  42. #define MAIN_VGA  1  /* for multi-VGA only */
  43. #define LEFT_VGA  2
  44. #define RIGHT_VGA 4
  45. #define ALL_VGA   7
  46.  
  47. extern void far VGA_select(int card);
  48.  
  49. This functions selects one (or all) video sources to be drawn to.
  50. If multiple bits are set (i.e to clear all sources in parallel, or
  51. to draw to the main monitor and one of the HMD eye sources at once,
  52. your driver should detect and handle this appropriately.
  53.  
  54. This function is reentrant (FARSTACK): see MEMMODEL for data.
  55. ----
  56. extern void far vsync();                /* pause till vert. retrace */
  57.  
  58. Self explanatory.  Used to setup the Sega/switcher timing, so it may
  59. be called from interrupt handlers.
  60.  
  61. This function is reentrant (FARSTACK): see MEMMODEL for data.
  62. ----
  63. extern void far set_vpage(int page);    /* set video page */
  64.  
  65. Since this may be called by an interrupt handler, it should
  66. NOT use BIOS calls to set the visible page.
  67.  
  68. This function is reentrant (FARSTACK): see MEMMODEL for data.
  69. ----
  70. #define PUT 0        /* defines of VGA write modes */
  71. #define AND 1   /* for use with setup_hdwe()  */
  72. #define OR  2
  73. #define XOR 3
  74.  
  75. extern void far setup_hdwe(int mode);  /* setup VGA for bunch of line */
  76.                              /* or poly draws: once per set */
  77.  
  78. extern void far reset_hdwe();  /* reset VGA to BIOS state after drawing */
  79.  
  80. Used to initialize hardware for drawing, and reset to standard mode after.
  81. The drawing modes are optional: passing 0 always is safest.  setup_hdwe()
  82. will be called before rendering screen polys etc; reset_hdwe() will be called
  83. afterwards.  It may be called at other times as well.
  84. -----
  85.              /* clear video page to solid color: 10 mS */
  86.              /* returns -1 if bad page #         */
  87. extern int far clr_page(int page, int color);
  88. -----
  89.             /* copy one page to another for use as */
  90.             /* background: 21 mS per call          */
  91.             /* returns -1 if bad page #            */
  92. extern int far copy_page(int source, int dest);
  93. ------
  94.             /* fast VGA line draw: about 15600 24-pixel */
  95.             /* vectors/sec (horizontal much faster)     */
  96. extern void far vgaline(int x1, int y1, int x2, int y2, int color);
  97. ------
  98. void far set_clip_rect(int l, int t, int r, int b);
  99.  
  100.             /* does C-S clipping and draws line   */
  101. extern void far clipline(int x1, int y1, int x2, int y2, int color);
  102.  
  103. These functions are not currently used by REND386, and may be stubbed off
  104. if desired.
  105. -----
  106. int far set_drawpage(int page);    /* set page for drawing on (0-7)   */
  107.  
  108. Use this to set page to draw to, for ALL functions that do not take a
  109. page number as an argument.
  110. -----
  111.             /* N_SIDED POLY DRAW for up to 20-sided  */
  112.             /* convex polygons.  Pass pointer to int */
  113.             /* array with X, Y coords in that order  */
  114.             /* and count.  No clipping, CCW order    */
  115.  
  116. void far fastpoly(int count, int far *pcoords, int color);
  117.  
  118.             /* same as fastpoly() but with color cycling */
  119.             /* and masking (halftone).  Color cycles in  */
  120.             /* its lowest 4 bits, up then down.  Bit 8   */
  121.             /* has been added as a "sign" bit for the    */
  122.             /* initial cycle direction. 0000000SHHHHCCCC */
  123.             /* the mask is XOR'ed with the toggle every  */
  124.             /* line for 2x8 halftone patterns            */
  125. void far m_fastpoly(int count, int far *pcoords, int color, int gmask, int toggle);
  126.  
  127. These functions should draw filled convex polygons from the point list
  128. given.  You can emulate them with triangle poly calls internally: the
  129. current REND386 slices the poly into trapezoidal segments and draws these.
  130.  
  131. The special-effects poly draw shoulds at least draw halftoned polys, using
  132. gmask as the drawing mask, and XORing it with toggle on odd lines.  The color
  133. argument is explained above, and should cycle up then down through a 16-color
  134. sequence.  See the assembly code for a better explanation.
  135. -----
  136.             /* print text in foreground only-- */
  137.             /* reversed = 1 for right-to-left  */
  138.             /* with x now right side of text   */
  139. void far printxyr(int x, int y, int color, char far *pstring, int reversed);
  140.  
  141. No background clearing is performed.  Should be capable of printing at
  142. any horizontal offset.  Reversed text prints left from start position,
  143. normal text prints right.  Reversed text is only used if one of your
  144. video devices will be used in horizontally-flipped mode: if none are,
  145. you may stub it off.  (Please support for widely-used drivers!).
  146. -----
  147.             /* draw "+" cursor on screen      */
  148.             /* save s screen under cursor       */
  149. void far draw_cursor(int x, int y, int color, int savebuff);
  150.  
  151.                  /* restores 8x8 area saved when   */
  152. void far erase_cursor(int savebuff); /* cursor was drawn               */
  153.  
  154. These are used for mouse cursor support.  The savebuff is device-specific,
  155. so would be seperate for each of multiple VGA cards, for example.  During
  156. cursor drawing, the screen under the cursor will be saved, then restore
  157. when rase_cursor is called.  There should be as many savebuff's as there are
  158. video pages on your device.
  159. -----
  160.             /* copy any byte-aligned rectangle   */
  161.             /* this is every 8 pixels (assumed for all modes)  */
  162.             /* x coords (left) are truncated to  */
  163.             /* left byte boundary: x size is     */
  164.             /* bumped up to next full 8-pixel count */
  165. extern int far copy_block(int spage, int sx, int sy,  /* source */
  166.                     int dpage, int dx, int dy,  /* dest   */
  167.                     int xs, int ys);            /* # lines, pixels */
  168.  
  169.             /* clear any byte-aligned block       */
  170.             /* 15-30% slower than full page clear */
  171.             /* left edge rounded down, right edge */
  172.             /* rounded up to nearest byte boundary */
  173. extern int far clr_block(int left, int top, int right, int bottom,
  174.                      int page, int color);
  175.  
  176. These should support the 8-pixel granularity as noted above for
  177. compatibility.
  178. -------
  179.             /* 3 entries each for n colors: RGB, 0->63 */
  180.             /* load always starts with slot 0          */
  181.             /* set pal=NULL for default (still give n) */
  182.             /* bw=1 will transform palette into B&W    */
  183. extern void far load_DAC_colors(char far *pal, int n, int bw);
  184.  
  185. extern void far read_DEC_colors(char far *pal, int n);
  186.  
  187. These should load or save the DAC palette.  The video driver should have its
  188. own private color table: pass NULL to use this table.  The table ideally
  189. should support the standard REND386 color mappings (see colormap.c).
  190. ------------------------------------------------
  191.  
  192. SUGGESTIONS:
  193.  
  194. Read through the 16- and 256- color VGA driver source if in doubt.
  195. Always debug you code by linking it into REND386 directly first.
  196. If you have trouble, suspect the memory-model interactions, and check for
  197. missing FAR declarations, etc.  If in doubt use TD386 to single-step
  198. through the REND386 calls to screen_data(), set_gmode(), and load_DAC_colors.
  199. ALWAYS check the validity of returned data.
  200.