home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 7 Games / 07-Games.zip / fly8112o.zip / grdriver.doc < prev    next >
Text File  |  1979-12-31  |  9KB  |  295 lines
  1. Creating a new graphics driver for Fly8
  2. =======================================
  3.  
  4. The structures
  5. ==============
  6.  
  7. A graphics driver is a structure which nominates some basic functions (the
  8. primitives) that Fly8 can utilise for it's graphics needs. Here is what
  9. this structure contains:
  10.  
  11. struct GrDriver {
  12.     char    *name;
  13.     Ushort    flags;
  14.     void    *extra;
  15.     DEVICE    *devices;
  16.     int    (FAR* Init) (DEVICE *dev, char *options);
  17.     void    (FAR* Term) (DEVICE *dev);
  18.     void    (FAR* MoveTo) (Uint x1, Uint y1);
  19.     void    (FAR* DrawTo) (Uint x2, Uint y2, Uint c);
  20. +    int    (FAR* SetVisual) (int page);
  21. +    int    (FAR* SetActive) (int page);
  22. +    void    (FAR* Clear) (SCREEN *scr);
  23. +    int    (FAR* WriteMode) (int mode);
  24. +    int    (FAR* SetPalette) (int index, long color);
  25. +    void    (FAR* DrawEllipse) (Uint x, Uint y, Uint rx, Uint ry, Uint c);
  26. +    void    (FAR* Flush) (void);
  27. +    int    (FAR* Shutters) (int eye);
  28. };
  29.  
  30. Except for the the function marked with '+', which may be set to NULL,
  31. the other fuctions must have valid values. A dummy function should be
  32. provided for unimplemented mandatory functions.
  33.  
  34. A reference to the driver should be included in the drivers register
  35. (normally 'drivers.c') like this:
  36.  
  37.     extern struct GrDriver NEAR GrFoo;
  38.     extern struct GrDriver NEAR GrBar;
  39.  
  40.     struct GrDriver NEAR* FAR GrDrivers[] = {
  41.         &GrFoo,
  42.         &GrBar,
  43.     0};
  44.  
  45. There can be more than one driver defined. The first one is the
  46. 'default' driver. You select a driver using the 'dv' option (for example
  47. 'dvFoo' of 'dvBar') as a Fly8 option.
  48.  
  49.  
  50. Associated with the driver is the 'device' information kept in a
  51. structure which is supplied to some of the calls.
  52.  
  53. struct device {
  54.     DEVICE    *next;
  55.     char    *name;
  56.     void    *pdevice;    /* private device data */
  57.     int    mode;        /* vga bios mode etc. */
  58.     int    colors;        /* number of colors */
  59.     int    minx;        /* physical */
  60.     int    miny;        /* physical */
  61.     int    sizex;        /* physical */
  62.     int    sizey;         /* physical */
  63.     int    npages;        /* how many display pages */
  64.     int    lengx;        /* millimeter */
  65.     int    lengy;        /* millimeter */
  66.     int    flags;        /* driver private */
  67. };
  68.  
  69.  
  70. Most of the fields come from the *.vmd line that was selected, and
  71. appear here in the same order. A quick look at a *.vmd file will clarify
  72. what these fields mean. The 'leng*' fields are actual screen measurments
  73. and are used to establish the pixel aspect ration. The 'Font*' are not
  74. used anymore so just leave these as '8'.
  75.  
  76. 'pdevice' is here to allow you to keep other private data associated
  77. with this device which you establish at Init() time and wish to access
  78. later.
  79.  
  80. You select a device using the 'V' and 'm' options, for example:
  81.     VFooBar m1024x768x256
  82.  
  83. The first options tells Fly8 to read the file 'FooBar.vmd', the second
  84. option tells it to look for a line identified as '1024x768x256' and use
  85. it's contents when building the 'device' structure.
  86.  
  87.  
  88. About color
  89. ===========
  90.  
  91. Fly8 uses a maximum of 16 colors (0-15) but will use more in the future.
  92. When a color is programmed, you are given an index and a color. You
  93. should set you palette and then store the color id into st.color[index].
  94. Fly8 will store the color itself (the RGB value) into st.palette[index].
  95.  
  96. The drawing functions (DrawTo and DrawEllipse) will be called with the
  97. contents of st.colors[index]. It is important to note that this is often
  98. NOT the same as the color index used inside Fly8.
  99.  
  100.  
  101. The Fields
  102. ==========
  103.  
  104.  
  105. char    *name;
  106. -------------
  107.  
  108. This is the driver's name. It is not case sensitive. This is the name
  109. that you will use to select this driver (with the 'dv*' option). It does
  110. not have to be the same as the structure name used for this driver.
  111.  
  112.  
  113. Ushort    flags;
  114. -------------
  115.  
  116. A general purpose flags word. Drivers store here status flags. Not used
  117. by Fly8 main part.
  118.  
  119. Normally left as zero.
  120.  
  121.  
  122. DEVICE    *devices;
  123. ----------------
  124.  
  125. The list of kind of devices that this driver can be set to use. This is
  126. an internalizes form of the *.vmd file contents. On PCs this actually
  127. represents one device that can be configured to operate in many forma
  128. (video modes). Define it as zero.
  129.  
  130.  
  131. void    *extra;
  132. --------------
  133.  
  134. This is an unused member. It is here to allow you to keep private
  135. information for use by this driver.
  136.  
  137. Normally left as NULL.
  138.  
  139.  
  140. int    (FAR* Init) (DEVICE *dev, char *options);
  141. ------------------
  142.  
  143. This is called when initializing a device. It should return 0 if
  144. successful.
  145.  
  146. This is the most involved procedure and needs to do a few things.
  147.  
  148. The 'options' field is not used in most cases but can allow users to
  149. supply special options to the driver through the command line (or
  150. fly.ini). You can see how it is used by msdos/grfast.c.
  151.  
  152. The 'dev' is a structure describing the device characteristics. You
  153. should attempt to make the graphics device operate in this mode.
  154. Otherwise you can modify the contents of this structure to reflect the
  155. mode achieved.
  156.  
  157. The device is expected to have a clear screen after this call is
  158. successful. However, the program will later clear the used area
  159. privately.
  160.  
  161. If you cannot double buffer then set 'dev->npages' to 1.
  162.  
  163.  
  164. void    (FAR* Term) (DEVICE *dev);
  165. ------------------
  166.  
  167. Called upon closing the device. Fly8 will not access the device after
  168. this call without calling Init() first.
  169.  
  170.  
  171. void    (FAR* MoveTo) (Uint x1, Uint y1);
  172. --------------------
  173.  
  174. Requsest to set a new current position on the screen. It does not draw
  175. any pixels. Many implementations will simply store the (x1, y1) values
  176. for later use during the line draw.
  177.  
  178. In Fly8, the (x, y) will be referenced to (0, 0) being the top left
  179. corner of the screen, 'x' is the horizontal position and 'y' is the
  180. vertical position. The positions any unsigned integers.
  181.  
  182.  
  183. void    (FAR* DrawTo) (Uint x2, Uint y2, Uint c);
  184. --------------------
  185.  
  186. Draw a line from the 'current position' to (x2, y2). The end pixel is
  187. expected to be drawn.
  188.  
  189. You can optimize the drawing by NOT drawing the end pixel if the next
  190. line starts at the same point. In this case some other calls will need
  191. to show the end pixel of the previous line segment.
  192.  
  193. The color 'c' is the value that was stored into st.colors[] when the
  194. color was programmed. It is expected to draw in the color that was then
  195. provided and stored into st.palette[].
  196.  
  197.  
  198. int    (FAR* SetVisual) (int page);
  199. -----------------------
  200.  
  201. Used for double buffering. It requests that you set the visible page to
  202. be as specified. In single buffered mode it is called only with the
  203. value 0 (zero) so you may wish to NOT implement it initially.
  204.  
  205.  
  206. int    (FAR* SetActive) (int page);
  207. -----------------------
  208.  
  209. Uset to set the active page (the one where pixels are being set in) to
  210. the specified page. Again, only really used for double buffering and can
  211. be left out initially.
  212.  
  213.  
  214. void    (FAR* Clear) (SCREEN *scr);
  215. -------------------
  216.  
  217. A request to clear the whole screen. If this is set to NULL then it is
  218. not called. Otherwise it is used to clear the screen before each frame.
  219. Note that on many systems this operation is expensive and erasing a
  220. image by re-tracing it with the background colour is faster (and this is
  221. what Fly8 will do if this is function not supplied).
  222.  
  223.  
  224. int    (FAR* WriteMode) (int mode);
  225. -----------------------
  226.  
  227. Sets the write mode to one of
  228.  
  229.   T_MSET
  230.     The standard 'overwrite' pixel setting.
  231.  
  232.   T_MOR
  233.     OR mode, each pixel value is ORed to the previous. Only used for
  234.     the red/blue stereo mode.
  235.  
  236.   T_MXOR
  237.     XOR mode. Not used by Fly8.
  238.  
  239. If not implemented then you will not be able to use the red/blue stereo
  240. mode, also the 'paused' message will fail to show. It should in this
  241. case be always drawing in 'set' mode.
  242.  
  243.  
  244. int    (FAR* SetPalette) (int index, long color);
  245. ------------------------
  246.  
  247. Called to set palette entry 'index' to the RGB value 'color'. Fly8 uses
  248. an RGB colour representation where red is the lower byte, green is the
  249. middle byte (mask 0x0000ff00L) and blue is the high byte (mask
  250. 0x00ff0000L).
  251.  
  252. You can extract the red, green and blue color componnents using:
  253.  
  254.     C_RGB_R (c)
  255.     C_RGB_G (c)
  256.     C_RGB_B (c)
  257.  
  258. If not implemented then the colors are expected to be fixed. Have a look
  259. at init.c to see what each color is expected to be and tray and assign
  260. good matches.
  261.  
  262.  
  263. void    (FAR* DrawEllipse) (Uint x, Uint y, Uint rx, Uint ry, Uint c);
  264. -------------------------
  265.  
  266. Draw an ellipse at position (x, y) with major axes (rx, ry) in colour
  267. 'c'. If your screen has square pixels then 'rx' will always be equal to
  268. 'ry' since Fly8 only needs to draw circels.
  269.  
  270. If not implemented then a 16 sided polygon will be drawn instead (and it
  271. does not look bad at all).
  272.  
  273.  
  274. void    (FAR* Flush) (void);
  275. -------------------
  276.  
  277. Request to flush any unfinished graphics primitives. It is called after
  278. the last graphics operation in a frame.
  279.  
  280. If not implemented then you are expected to make sure the image is on
  281. the screen in other ways.
  282.  
  283.  
  284. int    (FAR* Shutters) (int eye);
  285. ----------------------
  286.  
  287. Used to synchronize shutter glasses by turning on each eye in time. the
  288. values are
  289.      0    right (I think...)
  290.      1    left
  291.     -1    both on
  292.     -2    both off
  293.  
  294. If not implemented then this type of stereo view will not be available.
  295.