MultiPage VGA (MPVGA) 32-bits Graphic Library. Copyright (c) 1995 Lin Ke-Fong, Ethereal Software. Version 1.00 Last revision 12-4-95. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% MPVGA's documentation. Subtitle: How to become a MPVGA guru in five easy lessons for beginners. Contents 1 Introduction. a What is MultiPage VGA (MPVGA) Graphic Library ? b Hardware requirement. c Disclaimer, licence and other legal boring stuff. 2 How to use it ? a The tiny but really silly test program. b Full description of MPVGA's functions. c From theoric to practice. 3 Enhancements, limitations etc. a A very huge library. b Possible enhancements, the to do list. c Known, unknown and to be discovered bugs. d The VESA alternative. e A very lazy author. 4 More info about MPVGA. a Where can I found more info about SVGA cards ? b How to join me. c Thanks and greets. 5 Final words. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1 Introduction. a What is MultiPage VGA (MPVGA) Graphic Library ? MultiPage VGA (MPVGA) is a 32-bits graphic library which focus on providing multiple page mode 13h, the most used mode for fast or realtime applications such as games or demos. It allows the user to use a kind of mode X but with mode13h's easy linear memory arrangement and more pages. In fact, it depends of your video RAM size, if you have 256K, only 4 pages, but if you have 2048K, you can have 32 pages ! You can do double buffering or hardware scrolling, and use separate read/write bank if available on your card. The memory arrangement is the same as a "standard" 256 colors SVGA mode, you access the video memory through 64K banks, in MPVGA each bank corresponds to a page, but you are completely free to do differently. However it does not provide high level functions such as line(x1,y1,x2,y2) or copysprite(x,y,buffer), this is not the purpose of MPVGA. b Hardware requirement. The current MPVGA library have been written for Watcom C 386, but since it's written in a "portable" C code without asm inlines, it should be possible, with minor changes, to port it on DJGPP, Borland C, MSC, MSVC etc. More in section "3d Possible enhancements, the to do list". You need: * maybe a computer to start ? * at least a 386, the current MPVGA library is designed for 386 or plus, maybe there will be real mode versions. * some memory (depends of the type of your app.) * and of course a SVGA card. Here are the list of the supported SVGA cards: * Acer AliCat32/64 * Ahead V5000A/B * Avance Logic ALG21xx, ALG22xx, ALG23xx * Alliance * ARK Logic ARK1000VL, ARK_1000PV, ARK_2000PV * ATI 18800/18800-x/ATI GUP * Chips & Tech 45x/655xx/64xxx * Cirrus Logic 54xx/64xx * Compaq * HMC 304/314 * Matrox * MXIC MX86xxx * NCR 77c22, 77c22e, 77c22ep, 77c32blt * Oak * Primus P2000 * Realtek RT31xx * S3 * Sierra: * SiS * Trident 8800/8900/9000/9100/LX8200/9200CXr/9400CXi/94xx/96xx * Tseng ET3000, ET4000, ET4000w32 * UMC 408/418 * Video7 * Western Digital Paradise, 90cxx Mach32/Mach64, Weitek, IITAGX and XGA based cards, VESA 1.1+ supports should be implemented soon. Not supported cards: * Everex chips (does not support pageflip) * Genoa Chips (ditto) * Cirrus (ditto) * VESA 1.0 (ditto) c Disclaimer, licence and other legal boring stuff. DISCLAIMER: If you use MPVGA, you use this library package at your own risk. If my library makes your screen explode and blow off your head, or if you were too busy programming with my library, and forgot to turn off the gas and burned your house, I cannot be responsable, since you were aware of the danger and you were using MPVGA at your own risk, blah blah blah. In other word I'm not reponsible of the sadness and misfortune of this world. So if you think this disclaimer is unfair, just erase this package. LICENCE: MPVGA is what I called a CoolFreeShareWare, phew ! The basic rule of a CoolFreeShareWare is that it must be quite inexpensive and completely royalty free. You can use MPVGA or part of it in a freeware, shareware, commercial. In other word, it's not free, but nearly. The first part of the licence you have to pay to use MPVGA, is a beautiful postcard you will send me with some funny/cool words written on it. It's mandatory. My address is in section "4b How to join me". That was the cool part of the licence, now if you use MPVGA in a shareware or a commercial product, you must send me a complete registered copy. However if you make a freeware stuff, it's not forbidden to tell me where I can download it. The shareware part of the MPVGA is that you can always send me your money :-) And that I will never refuse two return tickets for a cruise in the Carribean, or any good gifts :-) If you are using MPVGA to make a new graphic library, I would be happy if you keep me informed of about your work, maybe I can help you or you can help me to enhance MPVGA. Last but not least I would also appreciate to be credited. 2 How to use it ? a The tiny but really silly test program. TEST.C is a test program which tries to detect the chip type of your graphic card, and do two tests. The first one is a basic pattern test, you should see SizeOfYourVRAM/64 times the test pattern, press any key between those test patterns. Then you should see a white bouncing ball. If those two tests failed, or if detection failed, please tell me, see how to join me in section 4b. You should find useful information about using MPVGA just by taking a glance at TEST.C. Here's a return form, please send it to me if TEST failed and even if it success, so I can be acknownledge that it works. ------------ 8< cut here ------------ 1 What is the name of your video card (ex: Speedstar 24X) ? 2 What is the video chip of your video card ? Please give me the full name, for example Trident 9200CXr. 3 What is the size of your video memory (in KiloBytes) ? 4 What video chip type and chip version have been reported by TEST ? Is it correct ? 5 What is the video memory size reported ? the BIOS video ram size ? Is it correct ? 6 TEST1 (the pattern test) ? Does it works ? Please describe. 7 TEST2 (the bouncing ball) ? Does it works ? Please describe. 8 Your feeling, your own tests, it works ? 9 Any comment ? 10 Name and address for possible reply and futher testing (not mandatory). ------------ 8< cut here ------------ b Full description of MPVGA's functions. int MPVGA_DetectChip (void); Detects the chip type and version of your graphic card, also detects the size of your video memory if possible. Returns Detected if a chip type have been recognized or NotDetected otherwise. Set MPVGA_ChipType version number, MPVGA_ChipVer chip version number, MPVGA_VideoRAMSize size of the video memory in kilobytes, and MPVGA_BiosRAMSize size of the video memory reported by BIOS. void MPVGA_SetMode (void); Set the multiple page mode 13h and enables extensions, set active & visual pages to page 0. void MPVGA_SetActivePage (int PageNumber); Selects the current writing/reading page, the first page is zero and the last page is (MPVGA_VideoRAMSize / 64)-1. Note: this function doesn't check the validity of his parameters, ie: if you ask page 20000 it will not complain, so becareful. void MPVGA_SetVisualPage (int PageNumber); Selects the current visual (displayed on screen) page. Same rules as MPVGA_SetActivePage applies for this function. void MPVGA_SetWriteBank (int Bank); Selects the current writing bank (64K). Note: for the cards who allow separate read/bank you must call MPVGA_SetReadBank(), if you want to write and read in this bank, since MPVGA doesn't automaticaly set read bank to the same as write bank. void MPVGA_SetReadBank (int Bank); Select the current reading bank (64K) if possible, if not it's equal to a sort NOP (No Operation). void MPVGA_SetVStart (int Sx, int Sy); SetVStart function, useful if you want to do hardware scrolling. Be careful if you also use function MPVGA_SetActivePage(). Now the variables: extern int MPVGA_ChipType; the chip number, take a look to the enum ChipType. extern int MPVGA_ChipVer; the version number, take a look to the enum ChipVer. extern int MPVGA_VideoRAMSize; size of the video RAM in kilobytes extern int MPVGA_BiosVRAMSize; video RAM size reported by BIOS functions if available note: MPVGA functions use MPVGA_VideoRAMSize, I trust no one ! The truth is out there ! That should be enough. c From theoric to practice. You should call once MPVGA_DetectChip() to detect the chip used by your graphic card, and to init thoses vars: * int MPVGA_ChipType * int MPVGA_ChipVer * int MPVGA_VideoRAMSize However you can do the detection part of your program in a separate executable, a SETUP.EXE for example, and save those three vars which are integers in a config file. And you can of course force detection of a chip by modifying those vars, take a look at the ChipType and ChipVer enum for more info. MPVGA_SetMode() is called to set mode 13h and enable extensions, at the start both active and visual pages are set to zero. When you quit you should set active and visual pages back to zero before you return to text mode or any other mode, you should do that as a precaution. I remarked that my Trident Windows driver bugs if I don't do so, may be you won't experience this problem, but it's a really cheap precaution that can avoid you many problems. In future version of MPVGA, maybe I will include a MPVGA_Exit() function, since it will be mandatory with Mach32/Mach64 chips based cards. Pay special attention when you are mixing both "higher level" functions MPVGA_SetActivePage() & MPVGA_SetVisualPage with "lower level" functions such as MPVGA_SetWriteBank(), MPVGA_SetReadBank(), and MPVGA_SetVStart(), since the high level functions use low level functions and can modify the machine state. Also when you are using MPVGA_SetWriteBank(), you must be careful to call MPVGA_SetReadBank() since on cards where separate read/bank is available, MPVGA will not automatically set the read bank to the same write bank. If your program don't want to use separate read/write bank feature, it should always follow a MPVGA_SetWriteBank() by a MPVGA_SetReadBank(). 3 Enhancements, limitations etc. a A very huge library. MPVGA is written in C since his functions shouldn't be called more than 70 times per second, so assembler isn't necessary. In fact assembler would not speed it up much more than a good C compiler. But the whole library is quite huge (about 30K), a complete rewrite in assembler would not really decrease the size of the library. Moreover a static library cannot be easily updated without a complete recompile. The best solution is to write dedicated loadable drivers for each cards, if there's a lot of support I will probably do so, but however I think I won't rewrite DETECT.C since detection should be done in a SETUP.EXE like program where size shouldn't be a problem. b Possible enhancements, the to do list. * support more graphic cards: Mach32/Mach64, Weitek, XGA, IITAGX, VESA etc. * correct bugs. * port to other C compiler, djgpp for example. * real mode version (maybe already obsolete). * write dedicated loadable drivers in assembler for each chips. c Known, unknown and to be discovered bugs. * Scroll is in unit of 4 bytes for ARK Logic 1000VL/2000PV, HMC 86c304, and All Western Digital chips. * Most of the S3 (not all) have a scroll in 4 or 8 bytes. d The VESA alternative. If MPVGA doesn't work on your graphic card, you can try to use VESA. Some VESA drivers support page flipping in mode 13h, for example my Trident 9200CXr built in VESA driver can do extended pageflip. That's why I will probably include VESA support in MPVGA, in case that MPVGA failed but not your favorite VESA driver. e A lazy author. One of the biggest limitation of MPVGA is myself :-) Yes it's true I'm a really lazy man, and if there's no support or no annoying guys who require the support of their SVGA cards or enhancement of MPVGA, I will not continue to update this small library. So please send me your postcards, and do good use of MPVGA, so I can be proud of my work and find it useful. Nothing would encourage me more than your support and your feedback. 4 More info about MPVGA. a Where can I found more info about programming SVGA cards ? VGADOC4B by Finn Thoegersen: garbo.uwasa.fi:/pc/doc-hard/vgadoc4b.zip and many more ftp sites. The ultimate SVGA information collection, extremely complete, most part of MPVGA is based on the knowledge in VGADOC. Email: finth@datashopper.dk WWW: http://www.datashopper.dk/~finth Surface: Finn Thoegersen Nordbanevej 3 C DK-7800 Skive Denmark VGAKIT60 by John Bridges: Unknown ftp site since I get it on BBS, probably available on Simtel, and many other ftp sites. A really good SVGA programming library even if it's a rather old. Compuserve ID: John Bridges [GRASP] 75300,2137 Internet: 75300.2137@compuserve.com (John Bridges) He says that he can be found regularly in the GRAPHVEN forum on Compuserve (where GRASP is supported), as well as the GRAPHSUP forum (formally called PICS). TWEAK?? by Robert Schmidt: oak.oakland.edu:/pub/msdos/vga/tweak10.zip there may be newer version of Tweak, but since I've never tried to get them, I don't know where they are. A really good utility for the adventurous developper who wants to tweak and explore his VGA card. Email (not sure): robert@idt.unit.no Surface (ditto): Robert Schmidt Ole Nordgaardsvei 44 N-7049 Trondheim NORWAY Books to read before sleeping: Richard F. Ferraro's Programmer's guide to the EGA, VGA and Super VGA cards: including XGA cards, 3rd ed. Addison-Wesley 1994. ISBN 0-201-62490-7. Some friends tell me that this book is the SVGA bible, but since it's not available in my university library and since I haven't buy it, I cannot confirm that. b How to join me. Here's my e-mail address, please do not overload it because I access it using an old and obsolete 2400 V22/V22bis modem, however feel free to ask me any questions and mail me if you need. lin.ke-fong@ace.epita.fr Here's my snail-mail address for your postcards, complete registered copy of your shareware/commercial products, money, gifts, bombs, etc. Lin Ke-Fong 23 rue Louis Fablet 94200 Ivry sur Seine France Here's my phone number, french speaking only, only for those who are dying to pay long range phone bill. phone: 33 1 46714542 c Thanks and greets. Great thanks to Finn Thoegersen and John Bridges since most part of MPVGA is based on informations from VGADOC4B and VGAKIT60. Great thanks also for the beta testers and those who are going to do beta tests. And finally great thanks for those I forgot to thank but who deserved to be thanked. Greets would goes to (in no particular order): Fred Peschanski Stephane Bailliez Pierre Emmanuel Baroiller Stephane "Ajt/Infiny" Thibert Tchi Southisong Emmanuel Rivoire Laurent Fagot Christophe "Gandalf/Infiny" Yvon Pierrick Russeil Edouard Berge Robert Schmidt Gerald Dalley Nigel Brooke Lespinasse "Walken/Impact Studios" Michel Patrick Descourtis, celui par qui Dieu est n‚ :) Cyril "Zool/Lithium" Bourbon Alexis Vaginay Anthony Ginepro Sylvain Chippaux Stephane "Bisounours/Tiny Toons" Gigandet Levan Sardjveladze Pierre Larbier And many more I've forgotten, just tell me and I will add you in the greet list. 5 Final words. Sorry for that poor english writing, it's not my everyday's language. Suggestions, feedbacks, criticisms, comments of any kind are welcomed. Happy coding and don't forget to send your postcard :)))