home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 15 / CDACTUAL15.iso / cdactual / program / basic / QBGFXLIB.ZIP / QBEVGFX.DOC < prev    next >
Encoding:
Text File  |  1990-10-04  |  17.4 KB  |  540 lines
  1.  
  2. Shareware Documentation            QB/EVGFX (C)1990 Cornel Huth
  3.  
  4. Complete documentation is available with registration.  See the
  5. end of this document for complete ordering information.
  6.  
  7. Shareware, def.  A try-before-you-buy marketing concept.  It
  8. relies on those that benefit from the product to pay for it.  Go
  9. ahead and try before you buy.  If you can't use it, pass it
  10. along, someone else may.  If you can and do use it, pay for it. 
  11. What do you get for your money?  Not only the legal continued use
  12. of the product but you also get personal support from the author. 
  13. Need something changed for a particular need?  Just ask.  Try
  14. that anywhere else.  Just remember, this product is not free, so
  15. if you use it please pay for it.
  16.  
  17.  
  18. OVERVIEW
  19.  
  20. QB/EVGFX is a set of graphic routines for the EGA and VGA
  21. assembled into a linkable LIB file.  All routines have been
  22. written in 8086 assembly and are self-contained.  In other words,
  23. even though QB/EVGFX has been designed for QuickBASIC 4.00+
  24. compilers, QuickBASIC itself is not needed.
  25.  
  26. QB/EVGFX requires an EGA or VGA compatible video card with at
  27. least 256K of RAM.  It can be used in any native EGA and VGA mode
  28. and also extended modes.  All these routines will work on either
  29. an EGA or VGA.
  30.  
  31. Accept the fact that these routines are for programmers. 
  32. Understand that this documentation is for programmers.
  33. If you are not completely familiar with QB, BC, LINK and LIB, do
  34. not fault this documentation.  Consult the appropriate reference
  35. or register this release to receive the 200-plus-page programmer
  36. reference manual.  The manual describes each routine completely
  37. and offers ideas on how it, and QB/EVGFX, can best be used.
  38.  
  39. ----------------------------------------------------------------
  40. * Some routines require a variable-length string in DGROUP as a 
  41. * parameter.  If you don't have this capability, see the section
  42. * on simulating this data structure.
  43. ----------------------------------------------------------------
  44.  
  45.  
  46. -----------------------
  47. QB/EVGFX COMMAND SUMMARY
  48.  VIDEO CONTROL ROUTINES
  49.  DRAWING ROUTINES
  50.  FONTS
  51.  MISC ROUTINES
  52.  
  53. -------------------------------
  54. VIDEO CONTROL ROUTINES include:
  55.  
  56. EGAVIDEO,VGAVIDEO,COLORVIDEO
  57. SETMODE,SETMODEX,GETMODE
  58. SETPSA,GETPSA
  59. SETPALREG,SETPALETTE
  60. SETSCNBUFF
  61. BLANKSCN
  62. BLINKBIT
  63. WAITVS
  64.  
  65.  
  66. FUNCTION EGAVIDEO%()
  67. EGAVIDEO returns -1 if EGA video is supported, 0 if not.
  68. Eg>IsEGA = EGAVIDEO
  69.  
  70.  
  71. FUNCTION VGAVIDEO%()
  72. VGAVIDEO returns -1 if VGA video is supported, 0 if not.
  73. Eg>IsVGA = VGAVIDEO
  74.  
  75.  
  76. FUNCTION COLORVIDEO%()
  77. COLORVIDEO returns -1 if color video is supported, 0 if not.
  78. Eg>IsColor = COLORVIDEO
  79.  
  80.  
  81. SUB SETMODE(mode%)
  82. SETMODE sets the computer's BIOS video to mode.  
  83. Normal EGA 640x350x16 graphics (QB SCREEN 9) is SETMODE 16.
  84. Normal VGA 640x480x16 graphics (QB SCREEN 12) is SETMODE 18.
  85. Eg>SETMODE &H10
  86.  
  87.  
  88. SUB SETMODEX(regax%,regbx%)
  89. SETMODEX is similar to SETMODEX but allows setting the computer's
  90. BIOS mode to an extended mode.  Most extended modes require only
  91. the AL register, in which case SETMODE can be used.  However,
  92. some video adapter's extended modes need an additional register
  93. to also be set (eg EVEREX).  Consult your adapter manual.
  94. Eg>SETMODEX &H0070,&H0
  95.  
  96.  
  97. FUNCTION GETMODE%()
  98. GETMODE returns the current BIOS video mode.
  99. Eg>VMode = GETMODE
  100.  
  101.  
  102. SUB SETPSA(onoff%)
  103. SETPSA activates/deactivates the palette save area. 
  104. SETPSA 1 activates the BIOS palette save area.  Any future
  105. changes in the palette will be stored there for later recall.
  106. SETPSA 0 deactivates the BIOS palette save area.  If you activate
  107. the PSA in your program you MUST deactivate it before the program
  108. ends.
  109. Eg>SETPSA 1
  110.  
  111.  
  112. SUB GETPSA(pal17$)
  113. GETPSA returns a table of palette values and border color.  The
  114. variable pal17$ is a variable length string in DGROUP. The first
  115. byte of pal17$ returned is the color value for attribute 0,
  116. second byte is attribute 1, and so on.  Byte 17 of pal17$ is the
  117. color border value.  This routine should only be used if there is
  118. an active palette save area (SETPSA 1).
  119. Eg>GETPSA pal17$
  120.  
  121.  
  122. SUB SETPALREG(reg%,colorval%)
  123. SETPALREG sets one of the palette registers.  Attribute 0 is
  124. controlled by register 0, attribute 1 by register 1...up to
  125. register 17 which is the border color.  Colorval is any color
  126. value between 0 and 63.
  127. Eg>SETPALREG 8,&H37
  128.  
  129.  
  130. SUB SETPALETTE(pal17$)
  131. SETPALETTE sets all 16 palette registers and the border with a
  132. single call.  The variable pal17$ is a variable length string in
  133. DGROUP.  The first byte of pal17$ is the color value for
  134. attribute 0, second byte is attribute 1, and so on.  Byte 17 of
  135. pal17$ is the border color value.  
  136. Eg>SETPALETTE pal17$
  137.  
  138.  
  139. SETSCNBUFF(x1%,y1%)
  140. SETSCNBUFF set the logical dimensions of the video display
  141. buffer.  This should be done after every video mode change. 
  142. Standard dimensions are x1%=640, y1%=350 for EGA mode 16,
  143. x1%=640,y1%=480 for VGA mode 18.
  144. Eg>SETMODE &H12
  145. Eg>SETSCNBUFF 640,480
  146.  
  147.  
  148. BLANKSCN(onoff%)
  149. BLANKSCN turns the video system on or off.
  150. BLANKSCN 1 turns the video off.
  151. BLANKSCN 0 turns the video back on.
  152. Eg>BLANKSCN 1
  153.  
  154.  
  155. BLINKBIT(onoff%)
  156. BLINKBIT allows selecting either 16 possible background values or
  157. 8 background values and 8 blinking.  The palette needs to be
  158. adjusted on the EGA before using BLINKBIT 1.
  159. Eg>BLINKBIT 1
  160.  
  161.  
  162. WAITVS(count%)
  163. WAITVS waits for count% vertical sync signals.  In EGA mode 16
  164. and VGA mode 18 a vert sync is at least 1/60th of a second. 
  165. Eg>WAITVS 1
  166.  
  167.  
  168. -------------------------
  169. DRAWING ROUTINES include:
  170.  
  171. READDOT,DRAWDOT
  172. DRAWCH
  173. SETSTEP,GETSTEP
  174. DRAWLN,DRAWLNP,DRAWLNS
  175. DRAWSTR
  176. DRAWELL
  177. FILLSCN,FILLAREA,FILLAREAP,FLUDAREA,FLUDAREAP
  178. DIMBLOCK,GETBLOCK,PUTBLOCK
  179.  
  180.  
  181. The x and y coordinates are screen coordinates with 0,0 at the
  182. upper-left of the screen.  x runs across, y runs down.
  183.  
  184. The value is an attribute value, 0 to 15.  Eg, using a value of 7
  185. would use the color value in attribute register 7.
  186.  
  187. The mode is the method used when updating the pixels.  A mode=0
  188. replaces the pixels, mode=8 ANDs the pixels, mode=16 ORs the
  189. pixels, and mode=24 XORs the pixels.
  190.  
  191.  
  192. FUNCTION READDOT%(x0%,y0%)
  193. READDOT returns the value of the pixel at position x0,y0.
  194. Eg>dot = READDOT(320,175)
  195.  
  196.  
  197. SUB DRAWDOT(mode%,value%,x0%,y0%)
  198. DRAWDOT sets the pixel by mode at position x0,y0 to value.
  199. Eg>DRAWDOT 0,7,320,175
  200.  
  201.  
  202. SUB DRAWCH(mode%,char%,x0%,y0%,fg%,bg%)
  203. DRAWCH draws ASCII char by mode at position x0,y0 in foreground
  204. value fg, background bg.
  205. Eg>DRAWCH 0,65,0,0,7,0
  206.  
  207.  
  208. SUB DRAWLN(mode%,value%,x0%,y0%,x1%,y1%)
  209. DRAWLN draws a line by mode from x0,y0 to x1,y1 in value.
  210. Eg>DRAWLN 0,7,0,0,639,349
  211.  
  212.  
  213. SUB DRAWLNP(mode%,pattern$,x0%,y0%,x1%,y1%)
  214. DRAWLNP draws a line by mode from x0,y0 to x1,y1 using the
  215. pattern pattern$.  The first byte of pattern$ is to be the shift
  216. count, the other bytes are the attribute values to use as the
  217. pattern.  Though not all that useful in DRAWLNP, the shift count
  218. lets you fill with diagonal patterns in the pattern fill
  219. routines. 
  220. Eg>pattern$=chr$(0)  'no shift after each line
  221. Eg>for i=1 to 15:pattern$ = pattern$ + chr$(i):next
  222. Eg>DRAWLNP 0,pattern$,0,0,320,175
  223.  
  224.  
  225. SUB SETSTEP(x0%,y0%)
  226. SETSTEP sets the x0,y0 point for DRAWLNS.
  227. Eg>SETSTEP 320,175
  228.  
  229.  
  230. SUB GETSTEP(x0%,y0%)
  231. GETSTEP returns the current x0%,y0% step point.
  232. Eg>GETSTEP x0,y0
  233. Eg>PRINT x0;y0   'x0=320,y0=175
  234.  
  235.  
  236. SUB DRAWLNS(mode%,value%,x1%,y1%)
  237. DRAWLNS draws a line by mode from step point to x1,y1 in value. 
  238. The initial step point is set using SETSTEP, thereafter, DRAWLNS
  239. updates the step point.  You cannot have any other QB/EVGFX
  240. routines between successive DRAWLNSs.
  241. Eg>DRAWLNS 0,7,310,160
  242.  
  243.  
  244. FUNCTION DRAWSTR%(mode%,strg$,x0%,y0%,fg%,bg%,gap%)
  245. DRAWSTR draws a text string by mode starting at x0,y0 in
  246. foreground value fg, background bg, with an inter-character gap
  247. of gap.  If gap=0 the inter-character gap is taken from the
  248. font's width table for proportional spacing.  DRAWSTR returns the
  249. next available x-position after the end of the string.
  250. Eg>nx=DRAWSTR(0,"Drawn in proportional space...",0,0,7,0,0)
  251.  
  252.  
  253. SUB DRAWELL(mode%,value%,xC%,yC%,maj%,min%)
  254. DRAWELL draws an ellipse by mode with the center at xC,yC with an
  255. x-radius of maj, y-radius of min, in value.
  256. Eg>DRAWELL 0,7,320,175,100,130
  257.  
  258.  
  259. SUB FILLSCN(lines%,value%)
  260. FILLSCN fills the screen buffer starting at 0,0 for lines count,
  261. in value.
  262. Eg>FILLSCN 350,0
  263.  
  264.  
  265. SUB FILLAREA(mode%,newval%,borderval%,x%,y%)
  266. FILLAREA will boundary-fill any shape by mode, bounded by
  267. borderval completely enclosing x,y, with newval.  For each level
  268. of complexity, FILLAREA uses 12 bytes of stack space.  Many areas
  269. can be filled with as little at 12 bytes (an empty circle) while
  270. others can require more, perhaps 1K (very complex).  In any case,
  271. by changing the DECLARE of FILLAREA from a SUB to a FUNCTION, you
  272. can get the maximum number of bytes used on the stack, say, for
  273. debugging purposes.
  274. Eg>DECLARE FILLAREA%(mode%,newval%,borderval%,x%,y%)
  275. Eg>maxbytes=FILLAREA(0,5,7,320,175)
  276.  
  277.  
  278. SUB FILLAREAP(mode%,pattern$,borderval%,x%,y%)
  279. FILLAREAP will boundary-fill any non-complex shape by mode,
  280. bounded by borderval completely enclosing x,y, with pattern$. 
  281. FILLAREAP cannot make complex pattern fills.  For complex pattern
  282. fills, use FLUDAREAP.  See DRAWLNP for the structure of pattern$.
  283. Eg>FILLAREAP 0,pattern$,7,320,175)
  284.  
  285.  
  286. SUB FLUDAREA(mode%,newval%,x%,y%)
  287. FLUDAREA will flood-fill any shape by mode that has the value at
  288. x,y, with newval.  The difference between FLUDAREA and FILLAREA
  289. is that FILLAREA stops when it reaches a borderval, going over
  290. any other value.  FLUDAREA stops when it reaches any value other
  291. than the value at the seed, x,y.  For stack usage, see FILLAREA.
  292. Eg>FLUDAREA 0,15,320,175
  293.  
  294.  
  295. SUB FLUDAREAP(mode%,pattern$,x%,y%)
  296. FLUDAREAP will flood-fill any shape by mode that has the value at
  297. x,y, with pattern$.  For stack usage, see FILLAREA.  See DRAWLNP
  298. for the structure of pattern$.
  299. Eg>FLUDAREAP 0,pattern$,320,175
  300.  
  301.  
  302. FUNCTION DIMBLOCK&(pmask%,x0%,y0%,x1%,y1%)
  303. DIMBLOCK is used to calculate the number of bytes needed to store
  304. the block defined by the upper-left coordinates x0,y0 and lower-
  305. right coordinates x1,y1, based on the plane mask, pmask.  Pmask
  306. is the mask value of planes to be used where 0 is no planes and
  307. 15 is all 4 planes (pmask=3 uses planes 0 & 1...).
  308. Eg>sz& = DIMBLOCK&(15,0,0,79,99)
  309. Eg>PRINT sz&   'size = 4006 bytes
  310.  
  311.  
  312. SUB GETBLOCK(pmask%,x0%,y0%,x1%,y1%,vseg%,voff%)
  313. GETBLOCK stores to RAM the block defined by the upper-left
  314. coordinates x0,y0 and the lower-right coordinates x1,y1, based on
  315. the plane mask, pmask.  The vseg and voff parameters are the
  316. VARSEG and VARPTR to the storage area in RAM.
  317. Eg>REDIM buff(0 TO sz&) AS STRING * 1
  318. Eg>GETBLOCK 15,0,0,79,99,VARSEG(buff(0)),VARPTR(buff(0))
  319.  
  320.  
  321. SUB PUTBLOCK(mode%,x0%,y0%,vseg%,voff%)
  322. PUTBLOCK stores to the video buffer by mode the block in RAM to
  323. the upper-left coordinates x0,y0.  The block in RAM is pointed to
  324. by the vseg and voff parameters.
  325. Eg>PUTBLOCK 0,1,1,VARSEG(buff(0)),VARPTR(buff(0))
  326.  
  327.  
  328. ----------------------
  329. FONT ROUTINES include:
  330.  
  331. FONTSYS08,FONTSYS14,FONTSYS16,FONTSRF14P
  332. USERFONT
  333.  
  334.  
  335. SUB FONTSYS08()
  336. FONTSYS08 makes the DRAWCH and DRAWSTR routines use the system
  337. 8x8 font in adapter ROM.
  338. Eg>FONTSYS08
  339.  
  340.  
  341. SUB FONTSYS14()
  342. FONTSYS14 makes the DRAWCH and DRAWSTR routines use the system
  343. 8x14 font in adapter ROM.
  344. Eg>FONTSYS14
  345.  
  346.  
  347. SUB FONTSYS16()
  348. FONTSYS16 makes the DRAWCH and DRAWSTR routines use the system
  349. 8x16 font in adapter ROM.  This is a VGA-only font.  On EGA
  350. systems this call will use the 8x14 font.
  351. Eg>FONTSYS16
  352.  
  353.  
  354. SUB FONTSRF14P()
  355. FONTSRF14P is the proportional font included in the shareware
  356. release of QB/EVGFX.  Many other fonts and a font editor are
  357. available.  With them the programmer can create callable or user
  358. fonts. 
  359. Eg>FONTSRF14P
  360.  
  361.  
  362. SUB USERFONT(vseg%,voff%,pts%)
  363. USERFONT defines a dynamic font.  By using this routine, the
  364. programmer can use fonts stored on disk rather than having all
  365. fonts linked in memory.  Vseg and voff point to the font data,
  366. pts is the height of the font.  The programmer allocates storage
  367. for the largest font to be used, then loads the font data from
  368. disk into the storage area.  The area can be reused.
  369. Eg>REDIM buff(0 TO 8448) AS STRING * 1 'max 32 pts+width table
  370. Eg>DoLOADUF font$,buff()
  371. Eg>USERFONT VARSEG(buff(0)),VARPTR(buff(0)),pts
  372.  
  373.  
  374. ----------------------
  375. MISC ROUTINES include:
  376.  
  377. GETBIT,SETBIT,XORBIT
  378.  
  379.  
  380. FUNCTION GETBIT%(BYVAL CheckMe%,BYVAL BitPos%)
  381. GETBIT returns non-zero if the bit at BitPos is set in CheckMe. 
  382. BitPos is 15-0 with bit 15 the most significant, 0 the least.
  383. Eg>set = GETBIT(CheckMe,15)
  384.  
  385.  
  386. FUNCTION SETBIT%(BYVAL UseMe%,BYVAL BitPos%)
  387. SETBIT sets the bit at BitPos returning the new value.
  388. Eg>UseMe = SETBIT(UseMe,0)
  389.  
  390.  
  391. FUNCTION XORBIT%(BYVAL XorMe%,BYVAL BitPos%)
  392. XORBIT toggles the bit at BitPos returning the new value.
  393. Eg>NewXorMe = XORBIT(XorMe,15)
  394.  
  395.  
  396.  
  397. -------------------------------------------------
  398. In addition to the shareware release of QB/EVGFX:
  399. QB/EVGFX2, QB/EVGFX plus window and 2-D routines:
  400.  
  401. SUB SETWIN2D(vseg2%,voff2%)
  402. SETWIN2D defines the 2-D window.
  403.  
  404. SUB GETWIN2D(vseg2%,voff2%)
  405. GETWIN2D returns the window definitions.
  406.  
  407. SUB SETSCNORG(x0%,y0%)
  408. SETSCNORG positions the hardware display start address allowing
  409. smooth-scrolling of the video buffer, page flipping...
  410.  
  411. FUNCTION DRAWSTRW%(mode%,strg$,x0%,y0%,fg%,bg%,gap%)
  412. DRAWSTRW is identical to DRAWSTR except it only draws characters
  413. that are within the defined window.
  414.  
  415. SUB DRAWELLW(mode%,value%,xC%,yC%,maj%,min%)
  416. DRAWELLW is identical to DRAWELL except that it draws only within
  417. the defined window.  DRAWELLW can also be used to draw arcs.
  418.  
  419. SUB FILLWIN(mode%,value%)
  420. FILLWIN fills the defined window with value.
  421.  
  422. SUB FILLWINP(mode%,pattern$)
  423. FILLWINP fills the defined window with pattern$.
  424.  
  425. SUB XFORM2D(vseg2%,voff2%)
  426. XFORM2D performs complete transformations in 2-D on any number of
  427. 2-D points.  Rotation degrees, rotational center, x-axis
  428. translation, y-axis translation, x-axis scale, y-axis scale, can
  429. all be done with a single call.
  430.  
  431. FUNCTION CLIP2D%(vsegln2%,voffln2%)
  432. CLIP2D performs the classic Sutherland-Cohen algorithm to clip
  433. lines to the defined window.  Approximately 1000 lines per second
  434. per MHz CPU speed can be clipped (33000 lines/sec on a 386/33).
  435.  
  436.  
  437.  
  438. ------------------------------------------------------------
  439. In addition to the shareware release QB/EVGFX and QB/EVGFX2:
  440. QB/EVGFX3, QB/EVGFX plus QB/EVGFX2 plus 3-D routines:
  441.  
  442. SUB SETWIN3D(vseg3%,voff3%)
  443. SETWIN3D defines the 3-D window.
  444.  
  445. SUB GETWIN3D(vseg3%,voff3%)
  446. GETWIN3D returns the window definitions.
  447.  
  448. SUB XFORM3D(vseg3%,voff3%)
  449. XFORM3D performs complete transformations in 3-D on any number of
  450. 3-D points.  Rotation heading, pitch, bank, rotational center, x-
  451.  & y- & z-axis translation, x- & y- & z-axis scale can all be
  452. done with a single call.
  453.  
  454. FUNCTION CLIP3D%(vsegln3%,voffln3%)
  455. CLIP3D performs the classic Sutherland-Cohen algorithm to clip
  456. lines to the defined window.  Approximately 1000 lines per second
  457. per MHz CPU speed can be clipped (33000 lines/sec on a 386/33).
  458.  
  459. SUB PROJORTHO(vseg3%,voff3%)
  460. PROJORTHO performs orthographic parallel projection conversion on
  461. a set of 3-D points.
  462.  
  463. SUB PROJPERS(vseg3%,voff3%)
  464. PROJPERS performs one-point perspective projection conversion on
  465. a set of 3-D points.
  466.  
  467.  
  468. -------------------------------
  469. SIMULATING NEAR VAR-LEN STRINGS
  470.  
  471. Declare the routine replacing $ with a %
  472. DECLARE FUNCTION DRAWSTR%(mode%,doff%,x0%,y0%,fg%,bg%,gap%)
  473.  
  474. Define a structure that will be stored in DGROUP.
  475. TYPE SIMSTRtype
  476. length AS INTEGER
  477. addr   AS INTEGER
  478. strg   AS STRING * 200   'or whatever max length you want
  479. END TYPE
  480. DIM SIMSTR AS SIMSTRtype
  481.  
  482. MID$(SIMSTR.strg,1,30) = "I'M REGISTERING QB/EVGFX, NOW!"
  483. SIMSTR.length = 30       
  484. SIMSTR.addr = VARPTR(SIMSTR.strg)
  485. nx = DRAWSTR(0,VARPTR(SIMSTR),0,0,7,0,8)
  486.  
  487.  
  488.  
  489.  
  490.  
  491. ORDERING INFORMATION
  492.  
  493.  
  494.  
  495.  
  496. Ship To:  
  497. ----------------------------------------------------------------
  498.  
  499. ----------------------------------------------------------------
  500.  
  501. ----------------------------------------------------------------
  502.  
  503. ----------------------------------------------------------------
  504.  
  505. ----------------------------------------------------------------
  506.  
  507.  
  508.                                Number             Extended
  509.                              of copies             amount
  510.  
  511.         QB/EVGFX registration         x $19.95 = $
  512.                                ------             --------
  513.                     QB/EVGFX2         x  39.95 =
  514.                                ------             --------
  515.                     QB/EVGFX3         x  59.95 =
  516.                                ------             --------
  517.        Font Editor with fonts*        x  19.95 =  
  518.                                ------             --------
  519.                                       Subtotal = $
  520.                                                   --------
  521.                   shipped to Texas, add 8% tax =
  522.                                                   --------
  523.                                          Total = $
  524.                                                   ========
  525.  
  526. All orders include the respective programmer's manual.  Upgrades
  527. are available at the difference in price plus $10.  All orders
  528. will receive update notices unless request is made otherwise.
  529.  
  530. *All orders received before June 30, 1991 will receive the font
  531. editor and fonts disk at no charge.
  532.  
  533. Send this order form with payment to:
  534.  
  535.            Cornel Huth
  536.            6402 Ingram Road
  537.            San Antonio, Texas  78238      Tele:(512)684-8065
  538.  
  539.  
  540.