home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / tools / bgi_tool / bgi.doc next >
Text File  |  1989-05-30  |  36KB  |  1,038 lines
  1.  
  2.  
  3.               -----------------------------
  4.               The BGI Driver Toolkit
  5.  
  6.  
  7.  
  8.  
  9.               Creating Device Drivers
  10.  
  11.              for the Borland Graphics Interface
  12.            --------------------------------------
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.          Copyright (c) 1988,89 Borland International
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                 Revision 1
  29.  
  30.                    May 15, 1989
  31.  
  32.  
  33.  
  34.  
  35.  
  36. Introduction
  37. =======================
  38.  
  39. The Borland Graphics Interface (BGI) is a fast, compact, and
  40. device-independent software package for graphics development built into the
  41. Turbo Pascal, Turbo C, and Turbo Prolog language products. Device
  42. independence is achieved via loadable device-specific drivers called from a
  43. common Kernel. This document describes basic BGI functionality, as well as
  44. the steps necessary to create new device drivers. Accompanying this
  45. document are files containing sample code and other pertinent information.
  46.  
  47. File Name          File Description
  48.  
  49. BH.C              BGI loader header building program source
  50. BH.EXE              BGI loader header building program
  51. DEVICE.INC          Structure and macro definition file
  52. DEBVECT.ASM          Vector table for sample (DEBUG) driver
  53. DEBUG.C              Main module for sample driver
  54. MAKEFILE          Build file
  55. BUILD.BAT          A batch file for MAKE-phobics
  56.  
  57. BGI Run-time Architecture
  58. =============================
  59.  
  60. Programs produced by Borland languages create graphics via two entities
  61. acting in concert: the generic BGI Kernel and a device-specific driver.
  62. Typically, an application built with a Borland compiler will include
  63. several device driver files on the distribution disk (extension .BGI) so
  64. that the program can run on various types of screens and printers.
  65. Graphics requests (for example, draw line, draw bar, etc.) are sent by the
  66. application to the BGI Kernel, which in turn makes requests of the device
  67. driver to actually manipulate the hardware.
  68.  
  69. A BGI device driver is a binary image; that is, a sequence of bytes without
  70. symbols or other linking information. The driver begins with a short
  71. header, followed by a vector table containing the entry points to the
  72. functions inside. The balance of the driver comprises the code and data
  73. required to manipulate the target graphics hardware.
  74.  
  75. All code and data references in the driver must be near (i.e., small model,
  76. offset only), and the entire driver, both code and data, must fit within
  77. 64K. In use, the device driver can count on its being loaded on a paragraph
  78. boundary. The BGI Kernel uses a register-based calling convention to
  79. communicate with the device driver (described in detail below).
  80.  
  81. BGI Graphics Model
  82. =======================
  83.  
  84. When considering the functions listed here, keep in mind that BGI performs
  85. most drawing operations using an implicit drawing or tracing color (COLOR),
  86. fill color (FILLCOLOR), and pattern (FILLPATTERN).  For example, the
  87. PIESLICE call accepts no pattern or color information, but instead uses the
  88. previously set COLOR value to trace the edge of the slice, and the
  89. previously set FILLCOLOR and FILLPATTERN values for the interior.
  90.  
  91. For efficiency, many operations take place at the position of the current
  92. pointer, or CP. For example, the LINE routine accepts only a single (x,y)
  93. coordinate pair, using the CP as the starting point of the line and the
  94. passed coordinate pair as the ending point. Many functions (LINE, to name
  95. one) affect CP, and the MOVE function can be used to explicitly adjust CP.
  96. The BGI coordinate system places the origin (pixel 0,0) at the upper
  97. left-hand corner of the screen.
  98.  
  99. Header Section
  100. =======================
  101.  
  102. The device header section, which must be at the beginning of the device
  103. driver, is built using macro BGI defined in file DEVICE.INC. The BGI macro
  104. takes the name of the device driver to be built as an argument. For
  105. example, a driver named DEBUG would begin as shown here:
  106.  
  107.   CSEG      SEGMENT PARA PUBLIC 'CODE'    ; any segment naming may be used
  108.       ASSUME  DS:CSEG, CS:CSEG    ; cs=ds
  109.  
  110.       CODESEG
  111.  
  112.       INCLUDE DEVICE.INC        ; include the device.inc file
  113.       BGI      DEBUG            ; declare the device header section
  114.  
  115. The device header section declares a special entry point known as EMULATE.
  116. If the action of a device driver vector is not supported by the hardware of
  117. a device, the vector entry should contain the entry EMULATE. This will be
  118. patched at load time to contain a jump to the Kernel's emulation routine.
  119. These routines will emulate the action of the vector by breaking down the
  120. request into simpler primitives. For example, if the hardware has the
  121. functionality to draw arc, the arc vector will contain the address
  122. of the routine to dispatch the arc data to the hardware and would
  123. appear as follows:
  124.  
  125.     dw    offset    ARC        ; Vector to the arc routine
  126.  
  127. If, as is often the case, the hardware doesn't have the functionality to
  128. display arcs, the vector would instead contain the EMULATE vector:
  129.  
  130.     dw    EMULATE
  131.  
  132. The Kernel has emulation support for the following vectors:
  133.  
  134.     BAR        Filling 3D rectangles
  135.     ARC        Elliptical arc rendering
  136.     PIESLICE    Elliptical pie slices
  137.     FILLED_ELLIPSE    Filled Ellipses
  138.  
  139. The Driver Status Table
  140. =======================
  141.  
  142. BGI requires that each driver contain a Driver Status Table (DST) to
  143. determine the basic characteristics of the device that the driver
  144. addresses. As an example, the DST for a CGA display is shown here:
  145.  
  146. STATUS STRUC
  147. STAT    DB    0        ; Current Device Status (0 = No Errors)
  148. DEVTYP    DB    0        ; Device Type Identifier (must be 0)
  149. XRES    DW    639        ; Device Full Resolution in X Direction
  150. YRES    DW    199        ; Device Full Resolution in Y Direction
  151. XEFRES    DW    639        ; Device Effective X Resolution
  152. YEFRES    DW    199        ; Device Effective Y Resolution
  153. XINCH    DW    9000        ; Device X Size in inches*1000
  154. YINCH    DW    7000        ; Device Y Size in inches*1000
  155. ASPEC    DW    4500        ; Aspect Ratio = (y_size/x_size) * 10000
  156.     DB    8h
  157.     DB    8h        ; for compatibility, use these values
  158.     DB    90h
  159.     DB    90h
  160. STATUS    ENDS
  161.  
  162. The BGI interface provides a system for reporting errors to the BGI Kernel
  163. and to the higher level code developed using Borland's language packages.
  164. This is done using the STAT field of the Driver Status Table. This field
  165. should be filled in by the driver code if an error is detected during the
  166. execution of the device installation (INSTALL). The following error codes
  167. are predefined in include file GRAPHICS.H for Turbo C and in the Graphics
  168. unit for Turbo Pascal.
  169.  
  170.    grOk              =   0    Normal Operation, No errors
  171.    grNoInitGraph      =  -1
  172.    grNotDetected      =  -2
  173.    grFileNotFound     =  -3
  174.    grInvalidDriver    =  -4
  175.    grNoLoadMem          =  -5
  176.    grNoScanMem          =  -6
  177.    grNoFloodMem       =  -7
  178.    grFontNotFound     =  -8
  179.    grNoFontMem          =  -9
  180.    grInvalidMode      = -10
  181.    grError          = -11    Generic Driver Error
  182.    grIOerror          = -12
  183.    grInvalidFont      = -13
  184.    grInvalidFontNum   = -14
  185.    grInvalidDeviceNum = -15
  186.  
  187. The next field in the Device Status Table, DEVTYP, describes the class of
  188. the device that the driver controls; for screen devices, this value is
  189. always 0.
  190.  
  191. The next four fields, XRES, YRES, XEFRES, and YEFRES contain the number of
  192. pixels available to BGI on this device in the horizontal and vertical
  193. dimensions, minus one. For screen devices, XRES=XEFRES and YRES=YEFRES.
  194. The XINCH and YINCH fields are the number of inches horizontally and
  195. vertically into which the device's pixels are mapped, times 1000. These
  196. fields in conjunction with XRES and YRES permit device resolution (DPI, or
  197. dots per inch) calculation.
  198.  
  199.     Horizontal resolution (DPI) = (XRES+1) / (XINCH/1000)
  200.     Vertical resolution (DPI)  = (YRES+1) / (YINCH/1000)
  201.  
  202. The ASPEC (aspect ratio) field is effectively a multiplier/divisor pair
  203. (the divisor is always 10000) that is applied to Y coordinate values to
  204. produce aspect-ratio adjusted images (e.g., round circles). For example,
  205. an ASPEC field of 4500 implies that the application will have to transform
  206. Y coordinates by the ratio 4500/10000 when drawing circles to that device
  207. if it expects them to be round. Individual monitor variations may require
  208. an additional adjustment by the application.
  209.  
  210.  
  211. The Device Driver Vector Table
  212. ==============================
  213.  
  214. The routines in the device driver are accessed via a vector table.
  215. This table is at the beginning of the driver and contains 16-bit
  216. offsets to subroutines and configuration tables within the driver.
  217. The format of the vector table is shown below.
  218.  
  219. VECTOR_TABLE:
  220.  
  221.     DW    INSTALL        ; Driver initialization and installation
  222.     DW    INIT        ; Initialize device for output
  223.     DW    CLEAR        ; Clear graphics device; get fresh screen
  224.     DW    POST        ; Exit from graphics mode, unload plotter, etc
  225.     DW    MOVE        ; Move Current Pointer (CP) to (X,Y)
  226.     DW    DRAW        ; Draw Line from (CP) to (X,Y)
  227.     DW    VECT        ; Draw line from (X0,Y0) to (X1,Y1)
  228.     DW    EMULATE        ; Reserved, must contain Emulate vector
  229.     DW    BAR        ; Filled 3D bar from (CP) to (X,Y)
  230.     DW    PATBAR        ; Patterned rectangle from (X,Y) to (X1,Y1)
  231.     DW    ARC        ; Define ARC
  232.     DW    PIESLICE    ; Define an elliptical pie slice
  233.     DW    FILLED_ELLIPSE    ; Draw a filled ellipse
  234.     DW    PALETTE        ; Load a palette entry
  235.     DW    ALLPALETTE    ; Load the full palette
  236.     DW    COLOR        ; Set current drawing color/background
  237.     DW    FILLSTYLE    ; Filling control and style
  238.     DW    LINESTYLE    ; Line drawing style control
  239.     DW    TEXTSTYLE    ; Hardware Font control
  240.     DW    TEXT        ; Hardware Draw text at (CP)
  241.     DW    TEXTSIZ        ; Hardware Font size query
  242.     DW    RESERVED    ; Reserved
  243.     DW    FLOODFILL    ; Fill a bounded region
  244.     DW    GETPIX        ; Read a pixel from (X,Y)
  245.     DW    PUTPIX        ; Write a pixel to (X,Y)
  246.     DW    BITMAPUTIL    ; Bitmap Size query function
  247.     DW    SAVEBITMAP    ; BITBLT from screen to system memory
  248.     DW    RESTOREBITMAP    ; BITBLT from system memory to screen
  249.     DW    SETCLIP        ; Define a clipping rectangle
  250.     DW    COLOR_QUERY    ; Color Table Information Query
  251. ;
  252. ;    35 additional vectors are reserved for Borland's future use.
  253. ;
  254.     DW    RESERVED    ; Reserved for Borland's use (1)
  255.     DW    RESERVED    ; Reserved for Borland's use (2)
  256.     DW    RESERVED    ; Reserved for Borland's use (3)
  257.     .
  258.     .
  259.     .
  260.     DW    RESERVED    ; Reserved for Borland's use (33)
  261.     DW    RESERVED    ; Reserved for Borland's use (34)
  262.     DW    RESERVED    ; Reserved for Borland's use (35)
  263. ;
  264. ;    Any vectors following this block may be used by
  265. ;    independent device driver developers as they see fit.
  266. ;
  267.  
  268.  
  269. Vector Descriptions
  270. ===================
  271.  
  272. The following information describes the input, output, and function
  273. of each of the functions accessed through the device vector table.
  274.  
  275.     DW    offset INSTALL        ; device driver installation
  276.  
  277. The Kernel calls the INSTALL vector to prepare the device driver for use. A
  278. function code is passed in AL. The following function codes are defined:
  279.  
  280. >>> Install Device:   AL = 00
  281.   Input:
  282.      CL = Mode Number for device
  283.  
  284.   Return:
  285.      ES:BX --> Device Status Table (see STATUS structure, above)
  286.  
  287. The INSTALL function is intended to inform the driver of the operating
  288. parameters that will be used. The device should not be switched to
  289. graphics mode (see INIT). On input, CL contains the mode in which the
  290. device will operate. (refer to BGI setgraphmode statement)
  291.  
  292.  
  293. The return value from the Install Device function is a pointer to a Device
  294. Status Table (described earlier).
  295.  
  296. >>> Mode Query:   AL = 001h
  297.   Input:
  298.      Nothing
  299.  
  300.   Return:
  301.      CX  The number of modes supported by this device.
  302.  
  303. The MODE QUERY function is used to inquire about the maximum number of
  304. modes supported by this device driver.
  305.  
  306.  
  307. >>> Mode Names:   AL = 002h
  308.   Input:
  309.      CX  The mode number for the query.
  310.  
  311.   Return:
  312.      ES:BX --> a Pascal string containing the name
  313.  
  314. The MODE NAMES function is used to inquire about the ASCII form of the mode
  315. number present in CX. The return value in ES:BX points to a Pascal string
  316. describing the given mode. (Note: A Pascal, or _length_, string is a string
  317. in which the first byte of data is the number of characters in the string,
  318. followed by the string data itself.) To ease access to these strings from
  319. C, the strings should be followed by a zero byte, although this zero byte
  320. should not be included in the string length. The following is an example
  321. of this format:
  322.  
  323.      NAME:    db    16, '1280 x 1024 Mode', 0
  324.  
  325.  
  326.     ==================================================================
  327.  
  328.      DW   offset   INIT        ; Initialize device for output
  329.  
  330.   Input:
  331.      ES:BX  --> Device Information Table
  332.  
  333.   Return:
  334.      Nothing
  335.  
  336. This vector is used to change an already INSTALLed device from text mode to
  337. graphics mode. This vector should also initialize any default palettes and
  338. drawing mode information as required. The input to this vector is a
  339. device information table (DIT). The format of the DIT is shown below and
  340. contains the background color and an initialization flag. If the device
  341. requires additional information at INIT time, these values can be appended
  342. to the DIT. There in no return value for this function. If an
  343. error occurs during device initialization, the STAT field of the Device
  344. Status Table should be loaded with the appropriate error value.
  345.  
  346. ; ************** Device Information Table Definition **************
  347.  
  348. struct    DIT
  349.     DB    0        ; Background color for initializing screen
  350.     DB    0        ; Init flag; 0A5h = don't init; anything
  351.                 ;   else = init
  352.     DB    64 dup 0    ; Reserved for Borland's future use
  353.                 ; additional user information here
  354. DIT    ends
  355.  
  356.  
  357.     ==================================================================
  358.  
  359.      DW   offset   CLEAR    ; Clear the graphics device
  360.  
  361.   Input:
  362.      Nothing
  363.  
  364.   Return:
  365.      Nothing
  366.  
  367. This vector is used to clear the graphics device to a known state. In the
  368. case of a CRT device, the screen is cleared. In the case of a printer
  369. or plotter, the paper is advanced, and pens are returned to the station.
  370.  
  371.  
  372.  
  373.     ==================================================================
  374.  
  375.      DW   offset   POST        ; Exit from graphics mode
  376.  
  377.   Input:
  378.      Nothing
  379.  
  380.   Return:
  381.      Nothing
  382.  
  383. This routine is used to close the graphics system. In the case of graphics
  384. screens or printers, the mode should be returned to text mode. For
  385. plotters, the paper should be unloaded and the pens should be returned to
  386. station.
  387.  
  388.  
  389.  
  390.     ==================================================================
  391.  
  392.      DW   offset   MOVE        ; Move the current drawing pointer
  393.  
  394.   Input:
  395.      AX        the new CP x coordinate
  396.      BX        the new CP y coordinate
  397.  
  398.   Return:
  399.      Nothing
  400.  
  401. Sets the Driver's current pointer (CP) to (AX,BX). This function is
  402. used prior to any of the TEXT, ARC, SYMBOL, DRAW, FLOODFILL, BAR, or
  403. PIESLICE routines to set the position where drawing is to take place.
  404.  
  405.  
  406.     ==================================================================
  407.  
  408.      DW   offset   DRAW        ; Draw a line from the (CP) to (X,Y)
  409.  
  410.   Input:
  411.      AX        The ending x coordinate for the line
  412.      BX        The ending y coordinate for the line
  413.  
  414.   Return:
  415.      Nothing
  416.  
  417.  
  418. Draw a line from the CP to (X,Y). The current LINESTYLE setting is used.
  419. The current pointer (CP) is updated to the line's endpoint.
  420.  
  421.  
  422.  
  423.     ==================================================================
  424.  
  425.     DW    VECT        ; Draw line from (X1,Y1) to (X2,Y2)
  426.  
  427.   Input:
  428.      AX        X1; The beginning X coordinate for the line
  429.      BX        Y1; The beginning Y coordinate for the line
  430.      CX        X2; The ending X coordinate for the line
  431.      DX        Y2; The ending Y coordinate for the line
  432.  
  433.   Return:
  434.      Nothing
  435.  
  436. Draws a line from the (X1,Y1) to (X2,Y2). The current LINESTYLE setting is
  437. used to draw the line. Note: CP is NOT changed by this vector.
  438.  
  439.  
  440.  
  441.     ==================================================================
  442.  
  443.     DW    BAR        ; fill and outline rectangle (CP),(X,Y)
  444.  
  445.   Input:
  446.      AX        X--right edge of rectangle
  447.      BX        Y--bottom edge of rectangle
  448.      CX        3D = width of 3D bar (ht := .75 * wdt); 0 = no 3D effect
  449.      DX        3D bar top flag; if CX <> 0, and DX = 0, draw a top
  450.  
  451.   Return:
  452.      Nothing
  453.  
  454. Fills and outlines a bar (rectangle) using the current COLOR, FILLCOLOR,
  455. and FILLPATERN. The current pointer defines the upper left corner of the
  456. rectangle and (X,Y) is lower right. An optional 3D shadow effect
  457. (intended for business graphics programs) is obtained by making CX nonzero.
  458. DX then serves as a flag indicating whether a top should be drawn on the
  459. bar.
  460.  
  461.  
  462.     ==================================================================
  463.  
  464.     DW    PATBAR        ; fill rectangle (X1,Y1), (X2,Y2)
  465.  
  466.   Input:
  467.      AX        X1--the rectangle's left coordinate
  468.      BX        Y1--the rectangle's top coordinate
  469.      CX        X2--the rectangle's right coordinate
  470.      DX        Y2--the rectangle's bottom coordinate
  471.  
  472.   Return:
  473.      Nothing
  474.  
  475. Fill (but don't outline) the indicated rectangle with the current fill
  476. pattern and fill color.
  477.  
  478.  
  479.     ==================================================================
  480.  
  481.     DW    ARC        ; Draw an elliptical arc
  482.  
  483.   Input:
  484.      AX        The starting angle of the arc in degrees (0-360)
  485.      BX        The ending angle of the arc in degrees (0-360)
  486.      CX        X radius of the elliptical arc
  487.      DX        Y radius of the elliptical arc
  488.  
  489.   Return:
  490.      Nothing
  491.  
  492. ARC draws an elliptical arc using the (CP) as the center point of the
  493. arc, from the given start angle to the given end angle. To get circular
  494. arcs the application (not the driver) must adjust the Y radius as follows:
  495.  
  496.      YRAD := XRAD * (ASPEC / 10000)
  497.  
  498. where ASPEC is the aspect value stored in the DST.
  499.  
  500.  
  501.     ==================================================================
  502.  
  503.     DW    PIESLICE    ; Draw an elliptical pie slice
  504.  
  505.   Input:
  506.      AX        The starting angle of the slice in degrees (0-360)
  507.      BX        The ending angle of the slice in degrees (0-360)
  508.      CX        X radius of the elliptical slice
  509.      DX        Y radius of the elliptical slice
  510.  
  511.   Return:
  512.      Nothing
  513.  
  514. PIESLICE draws a filled elliptical pie slice (or wedge) using CP as the
  515. center of the slice, from the given start angle to the given end angle.
  516. The current FILLPATTERN and FILLCOLOR is used to fill the slice and it is
  517. outlined in the current COLOR. To get circular pie slices, the application
  518. (not the driver) must adjust the Y radius as follows:
  519.  
  520.     YRAD := XRAD * ASPEC / 10000
  521.  
  522. where ASPEC is the aspect value stored in the driver's DST.
  523.  
  524.  
  525.  
  526.     ==================================================================
  527.  
  528.     DW    FILLED_ELLIPSE    ; Draw a filled ellipse at (CP)
  529.  
  530.   Input:
  531.      AX        X Radius of the ellipse
  532.      BX        Y Radius of the ellipse
  533.  
  534.   Return:
  535.      Nothing
  536.  
  537. This vector is used to draw a filled ellipse. The center point of the
  538. ellipse is assumed to be at the current pointer (CP). The AX Register
  539. contains the X Radius of the ellipse, and the BX Register contains the Y
  540. Radius of the ellipse.
  541.  
  542.  
  543.     ==================================================================
  544.  
  545.     DW    PALETTE        ; Load a color entry into the Palette
  546.  
  547.   Input:
  548.      AX        The index number and function code for load
  549.      BX        The color value to load into the palette
  550.  
  551.   Return:
  552.      Nothing
  553.  
  554. The PALETTE vector is used to load single entries into the palette. The
  555. register AX contains the function code for the load action and the index
  556. of the color table entry to be loaded. The upper two bits of AX determine
  557. the action to be taken. The table below tabulates the actions. If the
  558. control bits are 00, the color table index in (AX AND 03FFFh) is loaded
  559. with the value in BX. If the control bits are 10, the color table index in
  560. (AX AND 03FFFh) is loaded with the RGB value in (Red=BX, Green=CX, and
  561. Blue=DX). If the control bits are 11, the color table entry for the
  562. background is loaded with the value in BX.
  563.  
  564.  Control Bits        Color Value and Index
  565.  
  566.       00        Register BX contains color, AX is index
  567.       01        not used
  568.       10        Red=BX    Green=CX  Blue=DX, AX is index
  569.       11        Register BX contains color for background
  570.  
  571.     ==================================================================
  572.  
  573.     DW    ALLPALETTE    ; Load the full palette
  574.  
  575.   Input:
  576.      ES:BX --> array of palette entries
  577.  
  578.   Return:
  579.      Nothing
  580.  
  581. The ALLPALETTE routine loads the entire palette in one driver
  582. call. The register pair ES:BX points to the table of values to be loaded
  583. into the palette. The number of entries is determined by the color entries
  584. in the Driver Status Table. The background color is not explicitly loaded
  585. with this command.
  586.  
  587.  
  588.     ==================================================================
  589.  
  590.     DW    COLOR        ; Load the current drawing color.
  591.  
  592.   Input:
  593.      AL        The index number of the current drawing color
  594.      AH        The index number of the fill color
  595.  
  596.   Return:
  597.      Nothing
  598.  
  599. The COLOR vector is used to determine the current drawing color. The value
  600. in AL is the index into the palette of the new current drawing color. The
  601. value in the AH register is the color index of the new fill color.
  602. All primitives are drawn with the current drawing color until the color
  603. is changed.
  604.  
  605. The fill color is used for the interior color for the bar, polygons, pie
  606. slice, and floodfill primitives.
  607.  
  608.  
  609.     ==================================================================
  610.  
  611.     DW    FILLSTYLE    ; Set the filling pattern
  612.  
  613.   Input:
  614.      AL        Primary fill pattern number
  615.      ES:BX    If the pattern number is 0FFh, this points to user define
  616.         pattern mask.
  617.  
  618.   Return:
  619.      Nothing
  620.  
  621.  
  622. Sets the fill pattern for drawing. The fill pattern is used to fill all
  623. bounded regions (BAR, POLY, and PIESLICE). The numbers for the
  624. predefined fill patterns are as follows:
  625.  
  626. Code    Description            8 Byte fill pattern
  627.  
  628.   0      No Fill       000h, 000h, 000h, 000h, 000h, 000h, 000h, 000h
  629.   1      Solid Fill       0FFh, 0FFh, 0FFh, 0FFh, 0FFh, 0FFh, 0FFh, 0FFh
  630.   2      Line Fill       0FFh, 0FFh, 000h, 000h, 0FFh, 0FFh, 000h, 000h
  631.   3      Lt Slash Fill    001h, 002h, 004h, 008h, 010h, 020h, 040h, 080h
  632.   4      Slash Fill       0E0h, 0C1h, 083h, 007h, 00Eh, 01Ch, 038h, 070h
  633.   5      Backslash Fill   0F0h, 078h, 03Ch, 01Eh, 00Fh, 087h, 0C3h, 0E1h
  634.   6      Lt Bkslash Fill  0A5h, 0D2h, 069h, 0B4h, 05Ah, 02Dh, 096h, 04Bh
  635.   7      Hatch Fill       0FFh, 088h, 088h, 088h, 0FFh, 088h, 088h, 088h
  636.   8      XHatch Fill       081h, 042h, 024h, 018h, 018h, 024h, 042h, 081h
  637.   9      Interleave Fill  0CCh, 033h, 0CCh, 033h, 0CCh, 033h, 0CCh, 033h
  638.  10      Wide Dot Fill    080h, 000h, 008h, 000h, 080h, 000h, 008h, 000h
  639.  11      Close Dot Fill   088h, 000h, 022h, 000h, 088h, 000h, 022h, 000h
  640.  
  641.  0FFh      User is defining the pattern of the fill.
  642.  
  643. In the case of a user-defined fill pattern, the register pair ES:BX point
  644. to 8 bytes of data arranged as a 8x8 bit pattern to be used for the fill
  645. pattern.
  646.  
  647.  
  648.     ==================================================================
  649.  
  650.     DW    LINESTYLE    ; Set the line drawing pattern
  651.  
  652.   Input:
  653.      AL        Line pattern number
  654.      BX        User-defined line drawing pattern
  655.      CX        Line width for drawing
  656.  
  657.   Return:
  658.      Nothing
  659.  
  660. Sets the current line-drawing style and the width of the line. The line
  661. width is either one pixel or three pixels in width. The following table
  662. defines the default line styles:
  663.  
  664.    Code        Description             16 Bit Pattern
  665.   AL = 0      Solid Line Style            1111111111111111B
  666.   AL = 1      Dotted Line            1100110011001100B
  667.   AL = 2      Center Line            1111110001111000B
  668.   AL = 3      Dashed line            1111100011111000B
  669.   AL = 4      User-defined line style
  670.  
  671. If the value in AL is four, the user is defining a line style in the BX
  672. register. If the value in AL is not four, then the value in register BX is
  673. ignored.
  674.  
  675.  
  676.     ==================================================================
  677.  
  678.     DW    TEXTSTYLE    ; Hardware text style control
  679.  
  680.   Input:
  681.      AL        Hardware font number
  682.      AH        Hardware font orientation
  683.         0 = Normal,   1 = 90 Degree,   2 = Down
  684.      BX        Desired X Character (size in graphics units)
  685.      CX        Desired Y Character (size in graphics units)
  686.  
  687.   Return:
  688.      BX        Closest X Character size available (in graphics units)
  689.      CX        Closest Y Character size available (in graphics units)
  690.  
  691. The TEXTSTYLE vector is used to define the attributes of the hardware font
  692. for output. The parameters affected are the hardware font to be used, the
  693. orientation of the font for output, the desired height and width of the
  694. font output. All subsequent text will be drawn using these attributes.
  695.  
  696. If the desired size is not supported by the current device, the closest
  697. available match to the desired size should be used. The return value from
  698. this function gives the dimensions of the font (in pixels) that will
  699. actually be used.
  700.  
  701. For example, if the desired font is 8x10 pixels and the device supports
  702. 8x8 and 16x16 fonts, the closest match will be the 8x8. The output of the
  703. function will be BX = 8, and CX = 8.
  704.  
  705.  
  706.     ==================================================================
  707.  
  708.     DW    TEXT        ; Hardware text output at (CP)
  709.  
  710.   Input:
  711.      ES:BX    --> ASCII text of the string
  712.      CX        The length (in characters) of the string.
  713.  
  714. This function is used to send hardware text to the output device. The text
  715. is output to the device beginning at the (CP). The (CP) is assumed to be
  716. at the upper left of the string.
  717.  
  718.  
  719.     ==================================================================
  720.  
  721.     DW    TEXTSIZ        ; Determine the height and width of text
  722.                 ; strings in graphics units.
  723.  
  724.   Input:
  725.      ES:BX    --> ASCII text of the string
  726.      CX        The length (in characters) of the string.
  727.  
  728.   Return:
  729.      BX        The width of the string in graphics units.
  730.      CX        The height of the string in graphics units.
  731.  
  732. This function is used to determine the actual physical length and width of
  733. a text string. The current text attributes (set by TEXTSTYLE) are used to
  734. determine the actual dimensions of a string without displaying it. The
  735. application can thereby determine how a specific string will fit and reduce
  736. or increase the font size as required. There is NO graphics output for
  737. this vector. If an error occurs during length calculation, the STAT field
  738. of the Device Status Record should be marked with the device error code.
  739.  
  740.  
  741.     ==================================================================
  742.  
  743.     DW    FLOODFILL    ; Fill a bounded region using a flood fill
  744.  
  745.   Input:
  746.      AX        The x coordinate for the seed point
  747.      BX        The y coordinate for the seed point
  748.      CL        The boundary color for the Flood Fill
  749.  
  750.   Return:
  751.      Nothing      (Errors are returned in Device Status STAT field).
  752.  
  753. This function is called to fill a bounded region on bitmap devices. The
  754. (X,Y) input coordinate is used as the seed point for the flood fill. (CP)
  755. becomes the seed point. The current FILLPATTERN is used to flood the
  756. region.
  757.  
  758.  
  759.     ==================================================================
  760.  
  761.     DW    GETPIXEL    ; Read a pixel from the graphics screen
  762.  
  763.   Input:
  764.      AX        The x coordinate for the seed point
  765.      BX        The y coordinate for the seed point
  766.  
  767.   Return:
  768.      DL        The color index of the pixel read from the screen.
  769.  
  770. GETPIXEL reads the color index value of a single pixel from the graphics
  771. screen. The color index value is returned in the DL register.
  772.  
  773.  
  774.  
  775.     ==================================================================
  776.  
  777.     DW    PUTPIXEL    ; Write a pixel to the graphics screen
  778.  
  779.   Input:
  780.      AX        The x coordinate for the seed point
  781.      BX        The y coordinate for the seed point
  782.      DL        The color index of the pixel read from the screen.
  783.  
  784.   Return:
  785.      Nothing
  786.  
  787. PUTPIXEL writes a single pixel with the the color index value contained in
  788. the DL register.
  789.  
  790.  
  791.  
  792.     ==================================================================
  793.  
  794.     DW    BITMAPUTIL    ; Bitmap Utilities Function Table
  795.  
  796.   Input:
  797.      Nothing
  798.  
  799.   Return:
  800.      ES:BX    --> BitMap Utility Table.
  801.  
  802.  
  803. The BITMAPUTIL vector loads a pointer into ES:BX, which is the base of a
  804. table defining special case-entry points used for pixel manipulation.
  805. These functions are currently only called by the ellipse emulation routines
  806. that are in the BGI Kernel. If the device driver does not use emulation
  807. for ellipses, this entry does not need to be implemented. This entry was
  808. provided because some hardware requires additional commands to enter and
  809. exit pixel mode, thus adding overhead to the GETPIXEL and SETPIXEL vectors.
  810. This overhead affected the drawing speed of the ellipse emulation routines.
  811. These entry points are provided so that the ellipse emulation routines can
  812. enter pixel mode, and remain in pixel mode for the duration of the ellipse-
  813. rendering process.
  814.  
  815. The format of the BITMAPUTIL table is as follows:
  816.  
  817.   DW    offset    GOTOGRAPHIC    ; Enter pixel mode on the graphics hardware
  818.   DW    offset    EXITGRAPHIC    ; Leave pixel mode on the graphics hardware
  819.   DW    offset    PUTPIXEL    ; Write a pixel to the graphics hardware
  820.   DW    offset    GETPIXEL    ; Read a pixel from the graphics hardware
  821.   DW    offset    GETPIXBYTE    ; Return a word containing the pixel depth
  822.   DW    offset    SET_DRAW_PAGE    ; Select page in which to draw primitives
  823.   DW    offset    SET_VISUAL_PAGE ; Set the page to be displayed
  824.   DW    offset    SET_WRITE_MODE    ; XOR Line Drawing Control
  825.  
  826. The parameters of these functions are as follows:
  827.  
  828.     GOTOGRAPHIC    ; Enter pixel mode on the graphics hardware
  829.     This function is used to enter the special Pixel Graphics mode.
  830.  
  831.     EXITGRAPHIC    ; Leave pixel mode on the graphics hardware
  832.     This function is used to leave the special Pixel Graphics mode.
  833.  
  834.     PUTPIXEL    ; Write a pixel to the graphics hardware
  835.     This function has the same format as the PUTPIXEL entry described
  836.     above.
  837.  
  838.     GETPIXEL    ; Read a pixel from the graphics hardware
  839.     This function has the same format as the GETPIXEL entry described
  840.     above.
  841.  
  842.     GETPIXBYTE    ; Return a word containing the pixel depth
  843.     This function returns the number of bits per pixel (color depth) of
  844.     the graphics hardware in the AX register.
  845.  
  846.     SET_DRAW_PAGE    ; Select alternate output graphics pages (if any)
  847.     This function take the desired page number in the AL register and
  848.     selects alternate graphics pages for output of graphics primitives.
  849.  
  850.     SET_VISUAL_PAGE ; Select the visible alternate graphics pages (if any)
  851.     This function take the desired page number in the AL register and
  852.     selects alternate graphics for displaying on the screen.
  853.  
  854.     SET_WRITE_MODE    ; XOR Line drawing mode control. XOR Mode is selected
  855.     if the value in AX is one, and disabled if the value in AX is zero.
  856.  
  857.  
  858.  
  859.     ==================================================================
  860.  
  861.     DW    SAVEBITMAP    ; Write from screen memory to system memory
  862.  
  863.   Input:
  864.      ES:BX    Points to the buffer in system memory
  865.         to be written. ES:[BX] contains the width of the
  866.         rectangle -1. ES:[BX+2] contains the heigth of
  867.         the rectangle -1.
  868.  
  869.      CX        The upper left X coordinate of the rectangle.
  870.      DX        The upper left Y coordinate of the rectangle.
  871.  
  872.   Return:
  873.      Nothing
  874.  
  875. The SAVEBITMAP routine is a block copy routine that copies screen pixels
  876. from a defined rectangle as specified by (SI,DI) - (CX,DX) to the system
  877. memory.
  878.  
  879.  
  880.     ==================================================================
  881.  
  882.     DW    RESTOREBITMAP    ; Write screen memory to the screen.
  883.  
  884.   Input:
  885.      ES:BX    Points to the buffer in system memory
  886.         to be read. ES:[BX] contains the width of the
  887.         rectangle -1. ES:[BX+2] contains the heigth of
  888.         the rectangle -1.
  889.  
  890.      CX        The upper left X coordinate of the rectangle.
  891.      DX        The upper left Y coordinate of the rectangle.
  892.  
  893.      AL        The pixel operation to use when transferring
  894.         the image into graphics memory. Write mode for
  895.         block writing.
  896.           0: Overwrite mode
  897.           1: XOR mode
  898.           2: OR mode
  899.           3: AND mode
  900.           4: Complement mode
  901.  
  902.   Return:
  903.      Nothing
  904.  
  905. The RESTOREBITMAP vector is used to load screen pixels from the system
  906. memory. The routine reads a stream of bytes from the system memory into the
  907. rectangle defined by (SI,DI) - (CX,DX). The value in the AL register
  908. defines the mode that is used for the write. The following table defines
  909. the values of the available write modes:
  910.  
  911.     Pixel Operation            Code
  912.      Overwrite mode             0
  913.      Logical XOR             1
  914.      Logical OR             2
  915.      Logical AND             3
  916.      Complement             4
  917.  
  918.  
  919.     ==================================================================
  920.  
  921.     DW    SETCLIP        ; Define a clipping rectangle
  922.  
  923.   Input:
  924.      AX        Upper Left X coordinate of clipping rectangle
  925.      BX        Upper Left Y coordinate of clipping rectangle
  926.      CX        Lower Right X coordinate of clipping rectangle
  927.      DX        Lower Right Y coordinate of clipping rectangle
  928.  
  929.   Return:
  930.      Nothing
  931.  
  932. The SETCLIP vector defines a rectangular clipping region on the screen. The
  933. registers (AX,BX) - (CX,DX) define the clipping region.
  934.  
  935.  
  936.     ==================================================================
  937.  
  938.     DW    offset COLOR_QUERY    ; Device Color Information Query
  939.  
  940. This vector is used to inquire about the color capabilities of a given
  941. piece of hardware. A function code is passed into the driver in AL. The
  942. following function codes are defined:
  943.  
  944. >>> Color Table Size    AL = 000h
  945.   Input:
  946.      None:
  947.  
  948.   Return:
  949.      BX    The size of the color lookup table.
  950.      CX    The maximum color number allowed.
  951.  
  952. The COLOR TABLE SIZE query is used to determine the maximum number of
  953. colors supported by the hardware. The value returned in the BX register is
  954. the number of color entries in the color lookup table. The value returned
  955. in the CX register is the highest number for a color value. This value is
  956. usually the value in BX minus one; however, there can be exceptions.
  957.  
  958.  
  959. >>> Default Color Table    AL = 001h
  960.   Input:
  961.      Nothing
  962.  
  963.   Return:
  964.      ES:BX   --> default color table for the device
  965.  
  966. The DEFAULT COLOR TABLE function is used to determine the color table
  967. values for the default (power-up) color table. The format of this table is
  968. a byte containing the number of valid entries, followed by the given number
  969. of bytes of color information.
  970.  
  971.  
  972.  
  973.  
  974. Device Driver Construction Particulars
  975. ======================================
  976.  
  977. The source code for a sample, albeit unusual, BGI device driver is included
  978. with this Toolkit to assist developers in creating their own. The
  979. demonstration driver is provided in two files, DEBVECT.ASM and DEBUG.C.
  980. This "Debug" driver doesn't actually draw graphics, but instead simply
  981. sends descriptive messages to the console screen (via DOS function call 9)
  982. upon receiving commands. Instead of simply playing back commands, your own
  983. driver would be structured similarly, but would access control ports and
  984. screen memory to perform each function.
  985.  
  986.  
  987. Cookbook
  988. ========
  989.  
  990.     1. Compile or assemble the files required.
  991.  
  992.     2. Link the files together, making sure that the device vector
  993.        table is the first module within the link.
  994.  
  995.     3. Run EXETOBIN on the resulting .EXE or .COM file to produce a .BIN
  996.        file. There should be no relocation fixups required.
  997.  
  998.     4. Run program BH (provided with the toolkit) on the .BIN
  999.        file to produce the .BGI file.
  1000.  
  1001. The resulting driver is now ready for testing. Examine the file TEST.C for
  1002. an example of installing, loading, and calling a newly-created device
  1003. driver.
  1004.  
  1005.  
  1006.        Examples
  1007.  
  1008. ; To call any BGI function from assembly language, include the
  1009. ; structure below and use the CALLBGI macro.
  1010.  
  1011. CALLBGI MACRO    P
  1012.     MOV    SI,$&P            ; PUT OPCODE IN (SI)
  1013.     CALL    CS:DWORD PTR BGI_ADD    ; BGI_ADD POINTS TO DRIVER
  1014.     ENDM
  1015.  
  1016. ; e.g., to draw a line from (10,15) to (200,300):
  1017.  
  1018.     MOV    AX, 10
  1019.     MOV    BX, 15
  1020.     MOV    CX, 200
  1021.     MOV    DX, 300
  1022.     CALLBGI VECT
  1023.  
  1024.  
  1025.  
  1026. ; To index any item in the status table, include the status table
  1027. ; structures below and use the BGISTAT macro.
  1028.  
  1029. BGISTAT MACRO    P             ; GET ES:<SI> --> BGI STATUS
  1030.     LES    SI, CS:DWORD PTR STABLE  ; GET LOCATION OF STATUS TO SI
  1031.     ADD    SI, $&P             ; OFFSET TO CORRECT LOCATION
  1032.     ENDM
  1033.  
  1034. ; e.g., to obtain the aspect ratio of a device:
  1035.  
  1036.     BGISTAT ASPEC
  1037.     MOV    AX, ES:[SI]         ; (AX)= Y/X *10000
  1038.