C Library User Guide for the Professional Graphics Language Third Edition November, 1988 -------- Contents -------- i. Disclaimer ii. Trademark Information iii. Preface iv. Diskettes v. Related Documents I. Introduction II. Setting the Integer Precision Mode III. Command Prefixes IV. Application Notes V. Parameter Passing VI. Readbacks VII. Program Linking VIII. Device-Level PGL Command Listing IX. Device-Level Utility Commands X. System-Level Commands XI. Miscellaneous Commands XII. Global Data Structures ------------- i. Disclaimer ------------- While, to the best of our knowledge, this document contains accurate information, it is subject to change without notice. Vermont Microsystems cannot be held responsible for any errors, omissions, or misinformation that may appear in this document. Changes made to the information contained in this document will be incorporated in new editions. ------------------------- ii. Trademark Information ------------------------- Microsoft and MS-DOS are registered trademarks of the Microsoft Corporation. IBM and PS/2 are registered trademarks of IBM Corporation. ------------ iii. Preface ------------ Vermont Microsystems offers the Professional Graphics Language (PGL) C Library for the MS-DOS operating system. For users of other operating systems, the C Library Source Code is available and may be modified as needed. This user's guide contains information about the PGL C Library, including information on using the C Library with the MS-DOS operating system. It also contains information on the C Library source code. The section entitled "Device-Level PGL Command Listing" provides a complete listing of all the routines showing the C format for the library. For detailed descriptions of the commands, see the Professional Graphics Language Programmer's Reference manual. The C Library works in conjunction with an operating system device driver supplied with every Vermont Microsystems graphics device. The driver is specific to a given operating system. For MS-DOS, its file name is VMDOS.SYS. ------------- iv. Diskettes ------------- The C Library is provided on a single diskette holding multiple subdirectories. The diskette contains: 1. All C library source code. (\SRC) 2. Microsoft C 5.0 compatible library object code for (\) small and large model programs. 3. Make files used to build the object libraries. (\) 4. Test programs used to verify basic functionality. (\TEST) -------------------- v. Related Documents -------------------- Professional Graphics Language The Professional Graphics Language Programmer's Reference manual offers an introduction to the Professional Graphics Language and complete descriptions of the PGL commands. This manual is a companion to the graphics processor manual. Graphics Processor Manual The graphics processor manual is the device-specific manual that accompanies each Vermont Microsystems graphics processor. This manual includes product specifications, installation instructions, hardware-specific information, an architectural overview of the graphics processor, and the PGL commands supported only on that particular graphics processor. The title of the graphics processor manual varies with each different product. --------------- I. Introduction --------------- The Professional Graphics Language (PGL) C Library allows you to incorporate into your programs most PGL Version 2.0 commands and those commands specific to your graphics processor. Every PGL and graphics processor command is documented in the C Library. However, because several Vermont Microsystems graphics processors support hardware-specific commands, you may not be able to use every C Library command. When supported, these hardware-specific commands are documented in your graphics processor manual. Bullets (ù) highlight those C Library commands supported only by specific Vermont Microsystems graphics processors. Highlighted commands which are not documented in your graphics processor manual are not available with your particular graphics processor. In general the library makes no effort to ensure that only commands supported by the controlled device are issued. It is the responsibility of the aplication program to request only supported capabilities. The library's Device Configuration Record, described in the "Global Data Structures" section of this document, provides information to help you identify the connected device and its features. Although the format of the C Library commands closely follows that in the PGL and graphics processor manuals, there are some differences. For example, long lists of parameters (such as those used in PLINE) are loaded into arrays and passed by passing the address of the array. Where these differences exist, they are noted in the command listing. Most Vermont Microsystems graphics processors operate in conjunction with a system-level device driver. The C library uses this driver to open, close, and control the graphics processor. You will need to install the driver appropriate to your graphics processor prior to using any C library commands. Installation instructions are included with the driver. The C library comprises these distinct types of functions: 1. Device-level PGL commands. 2. Device-level utility commands. These commands provide functions supported by the hardware but not defined in PGL. 3. System-level commands. These functions enable the system to access the hardware. 4. Miscellaneous commands. These functions don't fall into any of the above catagories. You will find further information and command listings for each of the above functions in this document. ------------------------------------------------ II. Setting and Using the Integer Precision Mode ------------------------------------------------ Many PGL commands accept parameters in a special fixed point precision format. Fixed point data is 32 bits long, with 16 bits of whole number data and 16 bits of fractional data. When the graphics device operates in its normal mode, it expects 32 bits of data whenever a fixed point parameter is called for. The IPREC command sets a special integer precision mode. When the device is in this mode, it expects only 16 bits of whole number data in cases where it would normally require a fixed point value. While the initial state of the device is fixed point precision, after the call to VMOPEN, the library places it in integer precision mode. This mode provides for maximum performance, although at the cost of some precision. You can use the VMIPREC library function to change the precision mode at any time. PGL fixed-point parameters are passed to the library routines as floats, where the library converts them to the correct format for transmission to the device. Functions that expect floating point parameters have a name prefix of "vf", for example: vfcircle (radius) /* accepts a floating point parameter */ float radius; /* which it converts to fixed point */ Each function having one or more fixed point parameters also has an analog function prefixed by "vm". This analog expects an integer parameter wherever fixed point data indicated, for example: vmcircle (radius) /* accepts an integer parameter */ int radius; /* which it converts to fixed point */ The actual parameters transmitted to the device by both a "vf" routine or a "vm" routine depends on the current device mode. When in fixed point precision, a "vf" routine will use its floating point parameter(s) to generate 16 bits of fractional data. A "vm" routine generates 16 bits of zero for the fractional component. When in integer mode, a "vf" routine will truncate its parameter(s) to yield 16 bits of whole number data. A "vm" routine will transmit its parameter(s) directly. You should use the "vm" routine whenever you are in integer precision mode, as it eliminates the need to perform a float-to-int data conversion. When in fixed point precision, you can still use the "vm" function when you don't need the extra precision, as the "vm" routine will automatically pad the parameter with 16 bits of zero. In summary, if you use a "vm" routine when in fixed point precision, you will not take advantage of the extra precision provided by the device. If you use a "vf" routine when in integer precision, you will lose the precision embedded in your parameter(s) and incur the overhead of a float-to-int data conversion. --------------------- IV. Application Notes --------------------- Use the commands VMOPEN and VMCLOSE to bracket all calls to the C library. All library functions require that VMOPEN has been called and returns "success" status in order to operate properly. VMOPEN accepts a single parameter: VMOPEN (devname) UCHAR far *devname; Devname" is the name associated with the system level device driver, normally "CGB". After the call to VMOPEN, the device will be in hexadecimal communication mode, integer precision, and its flag will be reset (RESETF command). In order to view the high-resolution graphics screen of the device, you will generally need to make a call to the VMDISPLA function: VMDISPLA (0); This command causes your monitor to display the high-resolution graphics screen as opposed to the low-resolution "emulator" screen. -------------------- V. Parameter Passing -------------------- In passing parameters it is important that you pass the correct form of the parameter. For example, if the function requires a float parameter, the variable must be a float variable or constant. If the function requires an integer, the variable must be an integer variable or constant. All pointers passed to the library as parameters are passed as "far" pointers. A far pointer is one containing both segment and offset address information (4 bytes) and is the type normally used in the compact and large memory models. In programs build with the small or medium memory model, pointers normally contain only offset information (2 bytes). These pointers must be explicitly promoted to far pointers by means of a cast conversion prior to invoking a C library function. Alternative to explicit casting of parameters, you can include the header file VMPROTO.H at the beginning of each of your compilands. For each library function VMPROTO.H has a "function prototype", a declaration describing the data types of its parameters. Whenever possible, the C compiler will automatically do type conversions on the parameters so as to have them match the descriptions in the prototypes. Type mismatches in parameter passing result in errors. The variable type declared must match the declaration in the C library function. Thus, vfmove (X,Y) will result in erroneous operation if X and Y are declared as type integer. This restriction also applies to constants. The C language types constants based on the format of the constant. Therefore, the constant "100" is interpreted as type integer and the constant "100.0" as type float. Thus, vfmove (100,100) is in error and vfmove (100.0,100.0) is correct. Note however that if VMPROTO.H is included in your module, the compiler will perform the correct type conversion. ------------- VI. Readbacks ------------- Commands that read data from the device require that you pass the address of an array; data are then loaded into this array. (The format of the array is given in the command listing.) The first position(s) in this array usually holds the number of bytes being returned. It is up to the user to define enough space to hold the information being returned. This is of special importance when using the VMIMAGER() and VMBLKRD commands where the amount of data being returned may be quite large. Of course, the total amount of space that may be declared is dependent on the memory model used during compilation. -------------------- VII. Program Linking -------------------- The accompanying diskette contains these C library objects: SLIB_PGL.LIB ........ small model library LLIB_PGL.LIB ........ large model library These are appropriate for linking programs built for MS-DOS using the Microsoft C Compiler, version 5.0 or later. If you use another compiler, memory model, or operating system, you will need to build a library suitable to your needs. This may require modifications to the supplied source code. In the root directory of the diskette is the file MAKEFILE.S. This file was used to build the small model C library object. It can be used as a template to build a modified library. Note that you may need to change the path names specified by the macros at the beginning of the file. You will also find on your diskette a TEST directory. This directory contains files named TEST?.C and FTEST?.C (where ? is a number between 1 and 7); these are demonstration programs which offer samples of diagnostic tests for your reference. -------------------------------------- VIII. Device-Level PGL Command Listing -------------------------------------- This section provides a complete listing of all the routines showing the C format for the library. For detailed descriptions of the commands, see the PGL manual. Bullets (ù) highlight those C Library commands supported only by specific Vermont Microsystems graphics processors. Highlighted commands which are not documented in your graphics processor manual are not available with your particular graphics processor. The following data types are defined in VMDEFN.H and are used in the descriptions: #define UWORD unsigned int #define UCHAR unsigned char The C language automatically promotes parameters of type float to type double. References to a float parameter in the descriptions are made with the understanding that the called procedure will actually receive a double. -- A -- ARC vfarc (radius,deg0,deg1) float radius; UWORD deg0,deg1; vmarc (radius,deg0,deg1) UWORD radius, deg0, deg1; AREA vmarea () AREABC vmareabc (bcolor) UWORD bcolor; AREAPT vmareapt (ptrn) UWORD far *ptrn; Note: ptrn points to an array of 16 integers which define the desired pattern. -- B -- ù BCOLOR vmbcolor (color) UWORD color; BKVMOV vfbkvmov (x1,y1,x2,y2,xd,yd) float x1, y1, x2, y2, xd, yd; vmbkvmov (x1,y1,x2,y2,xd,yd) int x1, y1, x2, y2, xd, yd; BLINK vmblink (num) UCHAR num; BLKMOV vmblkmov (x1,y1,x2,y2,xd,yd) UWORD x1, y1, x2, y2, xd, yd; ù BLKRD vmblkrd (x1,y1,x2,y2,pixbuf,depth,pixoff) UWORD x1, y1, x2, y2, depth, pixoff; UCHAR far *pixbuf; Note: pixbuf is a pointer to an array that will receive the pixel data. Its size is dependent on parameters DEPTH and PIXOFF: If depth == 8, pixbuf[(x2-x1+1) * (y2-y1+1)] If depth == 1, pixbuf[((x2-x1+pixoff+8) / 8) * (y2-y1+1)] ù BLKWR vmblkwr (x1,y1,x2,y2,pixbuf,depth,pixoff) UWORD x1, y1, x2, y2, depth, pixoff; UCHAR far *pixbuf; Note: pixbuf is a pointer to an array holding the pixel data. Its size is dependent on parameters DEPTH and PIXOFF: If depth == 8, pixbuf[(x2-x1+1) * (y2-y1+1)] If depth == 1, pixbuf[((x2-x1+pixoff+8) / 8) * (y2-y1+1)] ù BUFDEF vmbufdef (bufnum,xsize,ysize,depth,access) UWORD bufnum, xsize, ysize, depth, access; ù BUFDEL vmbufdel (bufnum) UWORD bufnum; ù BUFMOV vmbufmov (src,dest,x1,y1,x2,y2,xd,yd) UWORD src, dest, x1, y1, x2, y2, xd, yd; ù BUFFER vmbuffer (mbank,dbank) UWORD mbank, dbank; -- C -- CA vmca () Note: The C library operates in hexadecimal mode only. Do not invoke a library function while in ASCII mode. CIRCLE vfcircle (radius) float radius; vmcircle (radius) UWORD radius; CLBEG vmclbeg (clist) UWORD clist; CLDEL vmcldel (clist) UWORD clist; CLEARS vmclears (color) UWORD color; CLEND vmclend () CLIPH vmcliph (flag) UWORD flag; ù CLIPR vmclipr (x1,x2,y1,y2) UWORD x1, x2, y1, y2; CLIPY vmclipy (flag) UWORD flag; CLOOP vmcloop (clist,count) UWORD clist, count; CLRD vmclrd (clist,buffptr) UWORD clist; UCHAR far *buffptr; Note: The first two positions pointed to by the buffptr in low byte/high byte format contain the number of elements in the array. Space must be reserved for the returned information. Even when in integer precision fixed-point data is returned in PGL fixed-point format. CLRUN vmclrun (clist) UWORDt clist; COLOR vmcolor (value) UWORD value; CONVPV vfconvpv (pixcoordx,pixcoordy,virtcoord) UWORD pixcoordx, pixcoordy; float far *virtcoord; Note: virtcoord points to an array of 2 floats that will receive the virtual coordinate. vmconvpv (pixcoordx,pixcoordy,virtcoord) UWORD pixcoordx, pixcoordy; int far *virtcoord; Note: virtcoord points to an array of 2 signed ints that will receive the virtual coordinate. CONVRT vmconvrt () CONVVP vfconvvp (virtcoordx,virtcoordy,pixcoord) float virtcoordx virtcoordy; UWORD far *pixcoord; Note: pixcoord points to an array of 2 unsigned ints that will receive the pixel coordinate. vmconvvp (virtcoordx, virtcoordy, pixcoord) int virtcoordx, virtcoordy; UWORD far *pixcoord; Note: pixcoord points to an array of 2 unsigned ints that will receive the pixel coordinate. CX vmcx () -- D -- DISPLA vmdispla (flag) UWORD flag; Note: This command is executed sequentially with those previous to it. For display mode changes that are executed immediately, use the device utility command IOCDSPLA. DISTAN vfdistan (dist) float dist; vmdistan (dist) int dist; DISTH vfdisth (dist) float dist; vmdisth (dist) int dist; DISTY vfdisty (dist) float dist; vmdisty (dist) int dist; DRAW vfdraw (x,y) float x, y; vmdraw (x,y) int x, y; DRAW3 vfdraw3 (x,y,z) float x, y, z; vmdraw3 (x,y,z) int x, y, z; DRAWR vfdrawr (dx,dy) float dx, dy; vmdrawr (dx,dy) int dx, dy; DRAWR3 vfdrawr3 (dx,dy,dz) float dx, dy, dz; vmdrawr3 (dx,dy,dz) int dx, dy, dz; -- E -- ELIPSE vfelipse (xrad,yrad) float xrad, yrad; vmelipse (xrad,yrad) UWORD xrad, yrad; -- F -- FILMSK vmfilmsk (mask) UWORD mask; FLAGRD vmflagrd (flag,inbuf) UWORD flag; UCHAR far *inbuf; Note: inbuf points to an array that will receive the data associated with the flag. It must be one byte larger than the total number of bytes returned by the device. On return, the first byte of the array equals the number of bytes returned by the command. Thus a flag that has two bytes of return data will have a 2 in the first byte of inbuf. The flag data will begin at inbuf[1]. The flag being read determines how the array should be interpreted. See the FLAGRD command in your PGL manual. FLOOD vmflood (color) UWORD color; -- I -- IMAGER vmimager (line,x1,x2,imgptr) UWORD line, x1, x2; UCHAR far *imgptr; Note: imgptr points to a user-declared array large enough to hold the image requested. It is up to the user to make sure that the allocated space is sufficient. The count of bytes is placed in the first two positions of the array in low byte/high byte format. Thus if 270 (0x10E) bytes of image data is received, imgptr will begin with <0x0E,0x01,...> When reading in multiple lines, adjust imgptr by this count value + 2 bytes before the next call to vmimager. Example: UCHAR image[10000]; UCHAR far *imptr; int count; imptr = (UCHAR far *)image; vmimager (20,0,100,imptr); /* read line 20 pixels */ count = (imptr[1] * 256) + imptr[0] + 2; imptr += count; vmimager (21,0,100,imptr); /* read line 21 pixels */ IMAGEW vmimagew (line,x1,x2,imgptr) UWORD line, x1, x2; UCHAR far *imgptr; Note: imgptr is an array with a two byte preamble like the one established by VMIMAGER. Thus VMIMAGEW can accept data developed by VMIMAGER unmodified. If you generate your own pixel array for use by VMIMAGEW, be sure that: 1. You establish the two byte preamble that gives the length of the pixel data. 2. You encode the pixel data in run-length-encoded format as described in the PGL reference manual. IMGSIZ vmimgsiz (xsize,ysize,depth,buffers) UWORD xsize, ysize, depth, buffers; IPREC vmiprec (flag) UWORD flag; Note: The library is set to iprec = 1 upon completion of the call to VMOPEN. -- L -- LINFUN vmlinfun (func) UWORD func; LINPAT vmlinpat (pattern) UWORD pattern; LOCCUR vmloccur () LOCMAP vflocmap (option,x1,x2,y1,y2) UWORD option; float x1, x2, y1, y2; vmlocmap (option,x1,x2,y1,y2) UWORD option; int x1, x2, y1, y2; LOCSIZ vmlocsiz (option,xsize,ysize) UWORD option, xsize, ysize; LOCXH vmlocxh (enable) UWORD int enable; LUT vmlut (index,r,g,b) UWORD index, r, g, b; LUT8 vmlut8 (index,r,g,b) UWORD index, r, g, b; LUT8RD vmlut8rd (index,color) UWORD index; UCHAR far *color; Note: Color points to an array of three bytes; on return, these three bytes represent the red, green, and blue values. LUTINT vmlutint (num) UWORD num; LUTRD vmlutrd (index,color) UWORD index; UCHAR far *color; Note: Color points to an array of three bytes; on return, these three bytes represent the red, green, and blue values. LUTSAV vmlutsav () -- M -- MASK vmmask (planemask) UWORD planemask; MATXRD vfmatxrd (index,matrix) UWORD index; float far *matrix; Note: Matrix points to an array of 16 floats where the requested matrix will be returned. vmmatxrd (index,matrix) UWORD index; int far *matrix; Note: Matrix points to an array of 16 ints where the requested matrix will be returned. MDIDEN vmmdiden () MDMATX vfmdmatx (matrix) float far *matrix; Note: Matrix points to an array of 16 floats holding the matrix data. vmmdmatx (matrix) int far *matrix; Note: Matrix points to an array of 16 floats holding the matrix data. MDORG vfmdorg (ox,oy,oz) float ox, oy, oz; vmmdorg (ox,oy,oz) int ox, oy, oz; MDROTX vmmdrotx (deg) int deg; MDROTY vmmdroty (deg) int deg; MDROTZ vmmdrotz (deg) int deg; MDSCAL vfmdscal (sx,sy,sz) float sx, sy, sz; vmmdscal (sx,sy,sz) int sx, sy, sz; MDTRAN vfmdtran (tx,ty,tz) float tx, ty, tz; vmmdtran (tx,ty,tz) int tx, ty, tz; MOVE vfmove (x,y) float x, y; vmmove (x,y) int x, y; MOVE3 vfmove3 (x,y,z) float x, y, z; vmmove3 (x,y,z) int x, y, z; MOVER vfmover (dx,dy) float dx, dy; vmmover (dx,dy) int dx, dy; MOVER3 vfmover3 (dx,dy,dz) float dx, dy, dz; vmmover3 (dx,dy,dz) int dx, dy, dz; MPOLY ù vfmpoly (npoly,nvert,ptr) UWORD npoly, far *nvert; float far *ptr[]; Note: npoly is the number of polygons; nvert is a pointer to an array containing the number of vertices in each polygon; ptr is a pointer to an array containing the addresses of each list of polygon vertices. The following is an example of the use of VFMPOLY. Assume polygon1 is a list of vertices for a 3 sided polygon and polygon2 is a list of vertices for a 10 sided polygon. float polygon1[6], polygon2[20]; int nvert[2], far *ptr[2]; polygon1[0] = ...; ...; polygon1[5] = ...; polygon2[0] = ...; ...; polygon2[19] = ...; nvert[0] = 3; nvert[1] = 10; ptr[0] = (float far *)&polygon1[0]; ptr[1] = (float far *)&polygon2[0]; vfmpoly (2,(int far *)nvert,(float far *(far *))ptr); ù vmmpoly (npoly,nvert,ptr) UWORD npoly, far *nvert; int far *ptr[]; Note: npoly is the number of polygons; nvert is a pointer to an array containing the number of vertices in each polygon; ptr is a pointer to an array containing the addresses of each list of polygon vertices. The following is an example of the use of VMMPOLY. Assume polygon1 is a list of vertices for a 3 sided polygon and polygon2 is a list of vertices for a 10 sided polygon. int polygon1[6], polygon2[20]; int nvert[2], far *ptr[2]; polygon1[0] = ...; ...; polygon1[5] = ...; polygon2[0] = ...; ...; polygon2[19] = ...; nvert[0] = 3; nvert[1] = 10; ptr[0] = (int far *)&polygon1[0]; ptr[1] = (int far *)&polygon2[0]; vmmpoly (2,(int far *)nvert,(int far *(far *))ptr); ù MPOLYR vfmpolyr (npoly,nvert,ptr) UWORD npoly, far *nvert; float far *ptr[]; vmmpolyr (npoly,nvert,ptr) unsigned int npoly, far *nvert int far *ptr[]; Note: These routines operate like vfmpoly and vmmpoly, respectively. -- O -- ù OCOLOR vmocolor (red,green,blue) UWORD red, green, blue; -- P -- ù PAN vmpan (x,y) int x, y; ù PICK vmpick (opt,ptr) int opt; UCHAR far *ptr; Note: ptr points to a 1 byte variable that will receive the value of the pick flag. PLINE vfpline (npts,ptr) UWORD npts; float far *ptr; vmpline (npts,ptr) int npts, far *ptr; Note: For both routines, ptr points to the the array holding the list of coordinates. PLINER vfpliner (npts,ptr) UWORD npts; float far *ptr; vmpliner (npts,ptr) int npts, far *ptr; Note: For both routines, ptr points to the the array holding the list of coordinates. POINT vmpoint () POINT3 vmpoint3 () POLY vfpoly (num,ptr) UWORD num; float far *ptr; vmpoly (num,ptr) UWORD num; int far *ptr; Note: For both routines, ptr points to the the array holding the list of coordinates. POLY3 vfpoly3 (num,ptr) UWORD num; float far *ptr; vmpoly3(num,ptr) UWORD num; int far *ptr; Note: For both routines, ptr points to the the array holding the list of coordinates. POLYR vfpolyr (num,ptr) UWORD num; float far *ptr; vmpolyr (num,ptr) UWORD num; int far *ptr; Note: For both routines, ptr points to the the array holding the list of coordinates. POLYR3 vfpolyr3(num,ptr) UWORD num; float far *ptr; vmpolyr3 (num,ptr) UWORD num; int far *ptr; Note: For both routines, ptr points to the the array holding the list of coordinates. PRMFIL vmprmfil (func) UWORD func; PROJCT vmprojct (angle) UWORD angle; PVEC vfpvec (nvec,coord) unsigned int nvec; float far *coord; vmpvec (nvec,coord) UWORD nvec; int far *coord; Note: For both routines, coord points to the the array holding the list of coordinates. PVECR vfpvecr (nvec,coord) unsigned int nvec; float far *coord; vmpvecr (nvec,coord) UWORD nvec; int far *coord; Note: For both routines, coord points to the the array holding the list of coordinates. -- R -- RBAND vmrband (type) UWORD type; READP vmreadp (color) UWORD far *color; Note: color is a pointer to a variable that will receive the color of the current 2D point. RECT vfrect (x,y) float x, y; vmrect (x,y) int x, y; RECTR vfrectr (x,y) float x, y; vmrectr (x,y) int x, y; RESETF vmresetf () -- S -- SECTOR vfsector (radius,deg0,deg1) float radius; UWORD deg0, deg1; vmsector(radius,deg0,deg1) int radius, deg0, deg1; -- T -- TANGLE vmtangle(flag) int flag; TDEFIN vmtdefin (ch,x,y,ptr) UWORD ch, x, y; UCHAR far *ptr; Note: ptr points to an array holding the text character definition. TEXT vmtext (count,str) int count; UCHAR far *str; TEXTP vmtextp (count,str) int count; UCHAR far *str; Note: In both cases str points to the string to be output. If this string is null-terminated, you may set count to -1, and the library will determine its length. TJUST vmtjust (horiz,vert) UWORD horiz, vert; TSIZE vftsize (size) float size; vmtsize(size) UWORD size; -- V -- ù VECTOR vmvector (x1,y1,x2,y2) int x1, y1, x2, y2; VWIDEN vmvwiden () VWMATX vfvwmatx (ptr) float far *ptr; vmvwmatx (ptr) int far *ptr; Note: In both cases ptr points to the matrix to be loaded. VMPORT vmvwport (x1,x2,y1,y2) UWORD x1, x2, y1, y2; VWROTX vmvwrotx (deg) int deg; VWROTY vmvwroty (deg) int deg; VWROTZ vmvwrotz (deg) int deg; VWRPT vfvwrpt (x,y,z) float x, y, z; vmvwrpt (x,y,z) int x, y, z; -- W -- WAIT vmwait (frames) UWORD frames; WINDOW vfwindow (x1,x2,y1,y2) float x1, x2, y1, y2; vmwindow (x1,x2,y1,y2) int x1, x2, y1, y2; -- X -- XHAIR vmxhair (enable,xsize,ysize) UWORD enable, xsize, ysize; XMOVE vmxmove (x,y) UWORD x, y; XVMOVE vfxvmove (x,y) float x, y; vmxvmove (x,y) int x, y; --------------------------------- IX. Device-Level Utility Commands --------------------------------- These commands provide functions supported by the hardware but not defined in the Professional Graphics Language. Not all commands are supported on every device. ioccfg (cfgrec) BDIDREC far *cfgrec; Returns the Device Configuration Record in the record pointed to by cfgrec. This record is also contained in global data structure vm_dvidrec. See the "Global Data Structures" section of this document (or header file VMDEFN.H) for a description of this record. ioccold ( ) Performs a cold restart on the currently open device. iocdspla (mode) UWORD mode; Sets the current display mode. This command operates asynchronously with respect to commands currently being processed by the device -- it takes place immediately. If you want the mode change synchronized with commands previously issued, use VMDISPLA. iocerflg (flag) UWORD flag; Enables/disables error input from the device (non-zero = enable). iocerrd (buf,count) UCHAR far *buf; UWORD count; Reads up to count bytes of error information from the device into the array pointed to by buf. Returns the number of bytes actually read, which depends on the current state of the device. Buf must be of size count+1 or greater. The error information is placed in buf[1] and following. Buf[0] is used (and modified) by iocerrd. ioclrev (buf) UWORD far *buf; Returns the current C library revision level as a version/revision and date. The revision is returned in BCD format. For example a C library version of 1.33, May 15, 1987 would be returned as (1,0x33,5,15,87). iocsfg (sfgrec) SYSIDREC far *sfgrec; Returns the System Configuration Record in the record pointed to by sfgrec. This record is also contained in global data structure vm_sysidrec. See the "Global Data Structures" section of this document (or header file VMDEFN.H) for a description of this record. iocwarm ( ) Performs a warm restart on the currently open device. ------------------------ X. System-Level Commands ------------------------ These commands enable the system to access the graphics device. vmclose () Closes the currently open device. This command should be issued at the completion of device activity. vmopen (devname) char far *devname; Opens the device for subsequent access. Devname is the name of system-level device driver, normally "CGB". vmopen returns a file descriptor which should be declared as an integer. A value other than -1 indicates that the device has been opened successfully. Note that this value may be negative. vmread (buf,count) UCHAR far *buf; UWORD count; Reads data from the readback facility of the device. Exactly count bytes of data will be read into the array pointed to by buf. Note that VMREAD does not return until the requested number of bytes are read. (*vm_iow) (bdb) BDB far *bdb; Writes data to the command facility of the device. Bdb is a pointer to a buffer definition block whose format is given in VMDEFN.H. Note that VM_IOW is a far pointer to a function, not a function itself. An example of the use of this capability: BDB bdb; /* ptr to bdb */ UCHAR buff[2]; /* command buffer */ extern int (far *vm_iow)(); /* library output function ptr */ buff[0] = ...; buff[1] = ...; bdb.ibuf = (UCHAR far *)buff; /* point bdb to buffer */ bdb.icount = 2; /* set transfer count */ bdb.iflags = 0x0000; /* no special operations */ (*vm_iow) ((BDB far *)&bdb); /* send data */ -------------------------- XI. Miscellaneous Commands -------------------------- These commands provide capabilities that don't fall into any of the above catagories. The following commands provide access to the device frame buffer via a "host interface": -- vmhstrd -- vmhstwr The following commands provide direct memory-mapped access to the device frame buffer: -- vmbufvis -- vmbufinv -- vmbufena -- vmbufdis -- vmgetadr -- vmadjadr The following commands provide other types of capability: -- vmsync ù UCHAR far *vmadjadr (fbptr,dir) UCHAR far *fbptr; int dir; This command adjusts a frame buffer address by one scan line. Only certain devices have the capability to provide visibility of their frame buffer. Refer to module VMXFRAME.C for further information on this command. ù vmbufdis () This command disables access to the device frame buffer. Only certain devices have the capability to provide visibility of their frame buffer. Refer to module VMXFRAME.C for further information on this command. ù vmbufena (flag) int flag; This command enables access to the device frame buffer. Only certain devices have the capability to provide visibility of their frame buffer. Refer to module VMXFRAME.C for further information on this command. ù UCHAR far *vmgetadr (x,y) UWORD x, y; This command converts a pixel address to a frame buffer address. Only certain devices have the capability to provide visibility of their frame buffer. Refer to module VMXFRAME.C for further information on this command. ù vmbufinv () This command disables visibility of the device frame buffer in the host address space. Only certain devices have the capability to provide visibility of their frame buffer. Refer to module VMXFRAME.C for further information on this command. ù vmbufvis (origin,flag,recptr) UWORD origin, flag; BINTREC far *recptr; This command makes the device frame buffer visible in the host address space. Only certain devices have the capability to provide visibility of their frame buffer. Refer to module VMXFRAME.C for further information on this command. ù vmhstrd (x1,y1,x2,y2,pixbuf,depth,pixoff) UWORD x1, y1, x2, y2, depth, pixoff; UCHAR far *pixbuf; This command reads pixel data from the device via the bitmap interface it provides. Only certain devices have a bitmap interface, which when available provides for higher performance that either VMIMAGER or VMBLKRD. Refer to module VMBLKRD.C to determine which devices support this command. Notes: The DEPTH and PIXOFF parameters are not used for color devices. PIXBUF is a pointer to an array that will receive the pixel data. Its size is equal to (x2-x1+1) * (y2-y1+1). ù vmhstwr (x1,y1,x2,y2,pixbuf,depth,pixoff) UWORD x1, y1, x2, y2, depth, pixoff; UCHAR far *pixbuf; This command writes pixel data tom the device via the bitmap interface it provides. Only certain devices have a bitmap interface, which when available provides for higher performance that either VMIMAGEW or VMBLKWR. Refer to module VMBLKRD.C to determine which devices support this command. Notes: The DEPTH and PIXOFF parameters are not used for color devices. PIXBUF is a pointer to an array that will receive the pixel data. Its size is equal to (x2-x1+1) * (y2-y1+1). vmsync () Waits until all pending commands have been processed by the device. When control is returned, the caller can be assured that the command stream is empty, and all readback and error data (if any) are available. --------------------------- XII. Global Data Structures --------------------------- After a successful call to VMOPEN, the library makes certain useful data structures available to the program. The most important of these are VM_DVIDREC, the device configuration record, and VM_SYSIDREC, the system configuration record. Their formats are detailed in header file VMDEFN.H, as follows: typedef struct /* device configuration record */ { int idxres; /* x resolution */ int idyres; /* y resolution */ int idplane; /* number of bits per pixel */ int idbid; /* board ID */ int idxid; /* extended ID */ int idver; /* firmware version */ int idrev; /* firmware revision */ int idflags; /* flags word */ int idoem; /* oem code */ int idresv[1]; /* reserved */ char idtext[16]; /* description text */ } BDIDREC; typedef struct /* system configuration record */ { int sid_ddvers; /* device driver version */ int sid_ddrev; /* device driver revision */ int sid_mem_base; /* memory base address */ int sid_io_base; /* i/o base address */ int sid_rom_base; /* rom base address */ int sid_bus_slot; /* system bus slot */ int sid_resv[4]; /***** reserved *****/ } SYSIDREC; Notes: 1. IDTEXT is a blank-terminated text string, not null-terminated. 2. IDFLAGS is currently not used. 3. SID_BUS_SLOT contains valid data only on IBM PS/2 platforms. In addition to these records, other global data structures are made available to the application. Refer to module VMDATA.C.