分类：
2011-05-31 20:46:14
-----------------------------
The BGI Driver Toolkit
Creating Device Drivers
for the Borland Graphics Interface
--------------------------------------
Copyright (c) 1988,89 Borland International
Revision 1
May 15, 1989
Introduction
=======================
The Borland Graphics Interface (BGI) is a fast, compact, and
device-independent software package for graphics development built into the
Turbo Pascal, Turbo C, and Turbo Prolog language products. Device
independence is achieved via loadable device-specific drivers called from a
common Kernel. This document describes basic BGI functionality, as well as
the steps necessary to create new device drivers. Accompanying this
document are files containing sample code and other pertinent information.
File Name File Description
BH.C BGI loader header building program source
BH.EXE BGI loader header building program
DEVICE.INC Structure and macro definition file
DEBVECT.ASM Vector table for sample (DEBUG) driver
DEBUG.C Main module for sample driver
MAKEFILE Build file
BUILD.BAT A batch file for MAKE-phobics
BGI Run-time Architecture
=============================
Programs produced by Borland languages create graphics via two entities
acting in concert: the generic BGI Kernel and a device-specific driver.
Typically, an application built with a Borland compiler will include
several device driver files on the distribution disk (extension .BGI) so
that the program can run on various types of screens and printers.
Graphics requests (for example, draw line, draw bar, etc.) are sent by the
application to the BGI Kernel, which in turn makes requests of the device
driver to actually manipulate the hardware.
A BGI device driver is a binary image; that is, a sequence of bytes without
symbols or other linking information. The driver begins with a short
header, followed by a vector table containing the entry points to the
functions inside. The balance of the driver comprises the code and data
required to manipulate the target graphics hardware.
All code and data references in the driver must be near (i.e., small model,
offset only), and the entire driver, both code and data, must fit within
64K. In use, the device driver can count on its being loaded on a paragraph
boundary. The BGI Kernel uses a register-based calling convention to
communicate with the device driver (described in detail below).
BGI Graphics Model
=======================
When considering the functions listed here, keep in mind that BGI performs
most drawing operations using an implicit drawing or tracing color (COLOR),
fill color (FILLCOLOR), and pattern (FILLPATTERN). For example, the
PIESLICE call accepts no pattern or color information, but instead uses the
previously set COLOR value to trace the edge of the slice, and the
previously set FILLCOLOR and FILLPATTERN values for the interior.
For efficiency, many operations take place at the position of the current
pointer, or CP. For example, the LINE routine accepts only a single (x,y)
coordinate pair, using the CP as the starting point of the line and the
passed coordinate pair as the ending point. Many functions (LINE, to name
one) affect CP, and the MOVE function can be used to explicitly adjust CP.
The BGI coordinate system places the origin (pixel 0,0) at the upper
left-hand corner of the screen.
Header Section
=======================
The device header section, which must be at the beginning of the device
driver, is built using macro BGI defined in file DEVICE.INC. The BGI macro
takes the name of the device driver to be built as an argument. For
example, a driver named DEBUG would begin as shown here:
CSEG SEGMENT PARA PUBLIC 'CODE' ; any segment naming may be used
ASSUME DS:CSEG, CS:CSEG ; cs=ds
CODESEG
INCLUDE DEVICE.INC ; include the device.inc file
BGI DEBUG ; declare the device header section
The device header section declares a special entry point known as EMULATE.
If the action of a device driver vector is not supported by the hardware of
a device, the vector entry should contain the entry EMULATE. This will be
patched at load time to contain a jump to the Kernel's emulation routine.
These routines will emulate the action of the vector by breaking down the
request into simpler primitives. For example, if the hardware has the
functionality to draw arc, the arc vector will contain the address
of the routine to dispatch the arc data to the hardware and would
appear as follows:
dw offset ARC ; Vector to the arc routine
If, as is often the case, the hardware doesn't have the functionality to
display arcs, the vector would instead contain the EMULATE vector:
dw EMULATE
The Kernel has emulation support for the following vectors:
BAR Filling 3D rectangles
ARC Elliptical arc rendering
PIESLICE Elliptical pie slices
FILLED_ELLIPSE Filled Ellipses
The Driver Status Table
=======================
BGI requires that each driver contain a Driver Status Table (DST) to
determine the basic characteristics of the device that the driver
addresses. As an example, the DST for a CGA display is shown here:
STATUS STRUC
STAT DB 0 ; Current Device Status (0 = No Errors)
DEVTYP DB 0 ; Device Type Identifier (must be 0)
XRES DW 639 ; Device Full Resolution in X Direction
YRES DW 199 ; Device Full Resolution in Y Direction
XEFRES DW 639 ; Device Effective X Resolution
YEFRES DW 199 ; Device Effective Y Resolution
XINCH DW 9000 ; Device X Size in inches*1000
YINCH DW 7000 ; Device Y Size in inches*1000
ASPEC DW 4500 ; Aspect Ratio = (y_size/x_size) * 10000
DB 8h
DB 8h ; for compatibility, use these values
DB 90h
DB 90h
STATUS ENDS
The BGI interface provides a system for reporting errors to the BGI Kernel
and to the higher level code developed using Borland's language packages.
This is done using the STAT field of the Driver Status Table. This field
should be filled in by the driver code if an error is detected during the
execution of the device installation (INSTALL). The following error codes
are predefined in include file GRAPHICS.H for Turbo C and in the Graphics
unit for Turbo Pascal.
grOk = 0 Normal Operation, No errors
grNoInitGraph = -1
grNotDetected = -2
grFileNotFound = -3
grInvalidDriver = -4
grNoLoadMem = -5
grNoScanMem = -6
grNoFloodMem = -7
grFontNotFound = -8
grNoFontMem = -9
grInvalidMode = -10
grError = -11 Generic Driver Error
grIOerror = -12
grInvalidFont = -13
grInvalidFontNum = -14
grInvalidDeviceNum = -15
The next field in the Device Status Table, DEVTYP, describes the class of
the device that the driver controls; for screen devices, this value is
always 0.
The next four fields, XRES, YRES, XEFRES, and YEFRES contain the number of
pixels available to BGI on this device in the horizontal and vertical
dimensions, minus one. For screen devices, XRES=XEFRES and YRES=YEFRES.
The XINCH and YINCH fields are the number of inches horizontally and
vertically into which the device's pixels are mapped, times 1000. These
fields in conjunction with XRES and YRES permit device resolution (DPI, or
dots per inch) calculation.
Horizontal resolution (DPI) = (XRES+1) / (XINCH/1000)
Vertical resolution (DPI) = (YRES+1) / (YINCH/1000)
The ASPEC (aspect ratio) field is effectively a multiplier/divisor pair
(the divisor is always 10000) that is applied to Y coordinate values to
produce aspect-ratio adjusted images (e.g., round circles). For example,
an ASPEC field of 4500 implies that the application will have to transform
Y coordinates by the ratio 4500/10000 when drawing circles to that device
if it expects them to be round. Individual monitor variations may require
an additional adjustment by the application.
The Device Driver Vector Table
==============================
The routines in the device driver are accessed via a vector table.
This table is at the beginning of the driver and contains 16-bit
offsets to subroutines and configuration tables within the driver.
The format of the vector table is shown below.
VECTOR_TABLE:
DW INSTALL ; Driver initialization and installation
DW INIT ; Initialize device for output
DW CLEAR ; Clear graphics device; get fresh screen
DW POST ; Exit from graphics mode, unload plotter, etc
DW MOVE ; Move Current Pointer (CP) to (X,Y)
DW DRAW ; Draw Line from (CP) to (X,Y)
DW VECT ; Draw line from (X0,Y0) to (X1,Y1)
DW EMULATE ; Reserved, must contain Emulate vector
DW BAR ; Filled 3D bar from (CP) to (X,Y)
DW PATBAR ; Patterned rectangle from (X,Y) to (X1,Y1)
DW ARC ; Define ARC
DW PIESLICE ; Define an elliptical pie slice
DW FILLED_ELLIPSE ; Draw a filled ellipse
DW PALETTE ; Load a palette entry
DW ALLPALETTE ; Load the full palette
DW COLOR ; Set current drawing color/background
DW FILLSTYLE ; Filling control and style
DW LINESTYLE ; Line drawing style control
DW TEXTSTYLE ; Hardware Font control
DW TEXT ; Hardware Draw text at (CP)
DW TEXTSIZ ; Hardware Font size query
DW RESERVED ; Reserved
DW FLOODFILL ; Fill a bounded region
DW GETPIX ; Read a pixel from (X,Y)
DW PUTPIX ; Write a pixel to (X,Y)
DW BITMAPUTIL ; Bitmap Size query function
DW SAVEBITMAP ; BITBLT from screen to system memory
DW RESTOREBITMAP ; BITBLT from system memory to screen
DW SETCLIP ; Define a clipping rectangle
DW COLOR_QUERY ; Color Table Information Query
;
; 35 additional vectors are reserved for Borland's future use.
;
DW RESERVED ; Reserved for Borland's use (1)
DW RESERVED ; Reserved for Borland's use (2)
DW RESERVED ; Reserved for Borland's use (3)
.
.
.
DW RESERVED ; Reserved for Borland's use (33)
DW RESERVED ; Reserved for Borland's use (34)
DW RESERVED ; Reserved for Borland's use (35)
;
; Any vectors following this block may be used by
; independent device driver developers as they see fit.
;
Vector Descriptions
===================
The following information describes the input, output, and function
of each of the functions accessed through the device vector table.
DW offset INSTALL ; device driver installation
The Kernel calls the INSTALL vector to prepare the device driver for use. A
function code is passed in AL. The following function codes are defined:
止处省略几万字。内容在压缩包中的BGI.doc文档中。
Device Driver Construction Particulars
======================================
The source code for a sample, albeit unusual, BGI device driver is included
with this Toolkit to assist developers in creating their own. The
demonstration driver is provided in two files, DEBVECT.ASM and DEBUG.C.
This "Debug" driver doesn't actually draw graphics, but instead simply
sends descriptive messages to the console screen (via DOS function call 9)
upon receiving commands. Instead of simply playing back commands, your own
driver would be structured similarly, but would access control ports and
screen memory to perform each function.
Cookbook
========
1. Compile or assemble the files required.
2. Link the files together, making sure that the device vector
table is the first module within the link.
3. Run EXETOBIN on the resulting .EXE or .COM file to produce a .BIN
file. There should be no relocation fixups required.
4. Run program BH (provided with the toolkit) on the .BIN
file to produce the .BGI file.
The resulting driver is now ready for testing. Examine the file TEST.C for
an example of installing, loading, and calling a newly-created device
driver.
Examples
; To call any BGI function from assembly language, include the
; structure below and use the CALLBGI macro.
CALLBGI MACRO P
MOV SI,$&P ; PUT OPCODE IN (SI)
CALL CS:DWORD PTR BGI_ADD ; BGI_ADD POINTS TO DRIVER
ENDM
; e.g., to draw a line from (10,15) to (200,300):
MOV AX, 10
MOV BX, 15
MOV CX, 200
MOV DX, 300
CALLBGI VECT
; To index any item in the status table, include the status table
; structures below and use the BGISTAT macro.
BGISTAT MACRO P ; GET ES:
LES SI, CS:DWORD PTR STABLE ; GET LOCATION OF STATUS TO SI
ADD SI, $&P ; OFFSET TO CORRECT LOCATION
ENDM
; e.g., to obtain the aspect ratio of a device:
BGISTAT ASPEC
MOV AX, ES:[SI] ; (AX)= Y/X *10000
全文结束(end) 如果那位英语好的朋友能帮我翻译一下就好。
 |
|
