home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 10 / mycd10.iso / share / os2 / sonido / ultra08a / toolkit / readme.doc < prev    next >
Encoding:
Text File  |  1995-08-24  |  8.3 KB  |  182 lines
  1. ********************************************************************************
  2.    OS/2 device driver interface to the Gravis Ultrasound family of soundcards 
  3.                 24-8-1995
  4.              Written by Sander van Leeuwen
  5.           email: s509475@dutiws.twi.tudelft.nl    
  6. ********************************************************************************
  7. This document is meant for programmers looking for an easy way to directly
  8. access the Gravis Ultrasound hardware, without developing their own device
  9. driver. MMPM/2 is good for writing multimedia applications, but it's not
  10. really suitable for writing modplayers or trackers (and probably some other
  11. software too) for wavetable soundcards.
  12.  
  13. I've developed a device driver, that offers a subset of the routines
  14. available in the GUS SDK, to support my OS/2 modplayer UltiMOD.
  15. After UltiMOD was released to the public a few months ago, Robert Manley 
  16. (the author of the GUS MMPM/2 drivers) and I joined forces to release one
  17. driver that provides both MMPM/2 support and a special MOD engine for my
  18. player. 
  19. This driver (version 0.7a) was released about three months ago.
  20. I've added a few more routines in the driver so you should have enough to 
  21. write (or port) your own player or tracker.
  22. The next section is a short introduction to programming the driver interface.
  23. I'm not going into too much detail, because the most calls were ported from
  24. the original GUS SDK. If you don't know what the calls do, just look them up
  25. in the docs that come with the Gravis SDK.
  26. There are a few extra calls, because OS/2 isn't quite like DOS. 8)
  27.  
  28. ********************************************************************************
  29.             Source Code
  30. ********************************************************************************
  31. This package contains:
  32.     - struct.h    typedefs of structures needed to communicate with the 
  33.             device driver
  34.     - ultradev.h    definitions of all the provided routines
  35.     - ultradev.c    source for communication with the driver
  36.     - readme.doc    this file
  37. This code compiles without errors using Watcom C/C++ v10. It will probably work
  38. with the other major OS/2 compilers  (IBM CSet and Borland C++) as I see no
  39. reason why it shouldn't.
  40.  
  41. IMPORTANT NOTE: To compile ultradev.c you should enable structure packing.
  42.         (not for your entire app, just for ultradev.c)    
  43. ********************************************************************************
  44.         Opening and closing the MMPM/2 Driver.
  45. ********************************************************************************
  46. The code below is pretty clear. You need to call UltraGetAccess in order to 
  47. prevent any other applications (OS/2, Windows or dos) to use the driver.
  48. This call return a value (> 0) when for some reason you didn't get exclusive
  49. access to the device driver. 
  50.  
  51. int InitDevice()
  52. {
  53.    APIRET status;
  54.    ULONG action;
  55.  
  56.    status = DosOpen( "ULTRA1$", &GUSHandle, &action, 0,
  57.               FILE_NORMAL, FILE_OPEN,
  58.    OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE | OPEN_FLAGS_WRITE_THROUGH,
  59.               NULL );
  60.    if(status)                   return(FALSE);
  61.    if(UltraGetAccess()) {
  62.     DosClose(GUSHandle);
  63.     return(FALSE); //not only owner
  64.    }  
  65. }
  66. To check whether or not the user is running the right version of the driver
  67. use the following call:
  68.     APIRET UltraGetDriverVersion(int *version)
  69. On return, the high word of version will contains the major version, the low 
  70. word the minor version of the driver.
  71. This API is only implemented in v0.8 (and will be supported in future releases),
  72. so with older drivers, DosDevIOCTl will return 31 (ERR_GEN_FAILURE).
  73.  
  74. To close the driver:
  75.     UltraReleaseAccess();    //gives other programs access to the GUS  
  76.     DosClose(GUSHandle);
  77.  
  78. ********************************************************************************
  79.         Original Gravis SDK calls.
  80. ********************************************************************************
  81. The following procdures work exactly as described in Gravis' GUS SDK:
  82. The calls use different return values though:
  83.     - 0     success
  84.     - > 0    error (returned by DosDevIOCtl)
  85.  
  86.     - UltraSetNVoices
  87.     - UltraEnableOutput
  88.     - UltraDisableOutput
  89.     - UltraMemInit
  90.     - UltraMemAlloc        
  91.     - UltraMemFree    
  92.     - UltraSizeDram
  93.     - UltraStartTimer
  94.     - UltraStopTimer
  95.     - UltraStartVoice
  96.     - UltraStopVoice
  97.     - UltraSetBalance    
  98.     - UltraSetFrequency    
  99.     - UltraVectorLinearVolume
  100.     - UltraDownload
  101.  
  102. The Peek/Poke calls aren't exactly the same as their SDK equivalents.
  103. There's no need to specify the Ultrasound's baseport.
  104.     APIRET UltraPokeData(long, int);
  105.     - UltraPokeData        
  106.  
  107. UltraPeekData expects (a pointer to) the address, from which you wish to 
  108. read data, as a parameter. It returns this data in this parameter.
  109.     APIRET UltraPeekData(int *);
  110.     - UltraPeekData        
  111.     
  112. You don't need to call UltraMemInit when initializing the GUS. This call
  113. is just an easy way to release all reserved memory. 
  114. ********************************************************************************
  115.         Writing a multithreaded player    
  116. ********************************************************************************        
  117. When programming for OS/2 you should put time consuming task in a separate 
  118. thread, so it's a good idea to do this for your plackback procedure(s).
  119. Use DosSetPriority to give the thread the highest priority. (to make sure the
  120. music will be played smoothly)
  121. OS/2 isn't a realtime system, so your thread might not always get a time slice
  122. in time. (especially when the system load is quite high)
  123.  
  124. In OS/2 ring 3 applications cannot change the interrupt vector table, so you
  125. need the next solution: 
  126.     DosSetPriority(PRTYS_THREAD, PRTYC_TIMECRITICAL, 31, 0);
  127.  
  128.     while(!Fatal) //StopPlaying changes Fatal to TRUE
  129.     {
  130.       UltraBlockTimerHandler1();
  131.       DoYourStuff();        //proccess song data
  132.       .....Update the voices (vol, freq, balance)
  133.     }  //while
  134. To start playing you start timer 1 (UltraStartTimer).
  135. UltraBlockTimerHandler1 blocks the thread until timer 1 on the GUS produces an
  136. interrupt. (UltraBlockTimerHandler2 does the same, but for timer 2)
  137.  
  138. UltraUnBlockAll unblocks the blocked threads, so they can return to your code.
  139. You SHOULDN'T use DosKillThread to kill a thread that's blocked in the driver.
  140. This doesn't work and will cause your program to hang. Once it's hung, you
  141. can't kill it. 
  142. If you application crashes, it can occur that the thread(s) will stay stuck in-
  143. side the driver. 
  144. OS/2 should unblock threads blocked in a driver, when the application crashes,
  145. but most of the time this doesn't work. Don't ask me why.
  146. A solution for this is to set an exception handler that unblocks the play
  147. thread whenever something bad happens (div/0, protection violation etc)
  148. (this is very easy, just look it up in the online OS/2 API reference)
  149.  
  150. UltraSetAll is a way to update the balance, frequency & volume settings for a
  151. voice in one DevIOCTL call. When you need to update these three settings for
  152. a voice, this call saves a lot of time. 
  153.  
  154. ********************************************************************************
  155. ********************************************************************************
  156. As you might have noticed I've removed a few of the DevIOCTL calls in 
  157. ultradev.c. 
  158. I use these in my modplayer to improve the efficiency. These routines are very
  159. dependant on my channel structures and overal program structure so they aren't
  160. usefull to you.
  161. You shouldn't call them though. At least two of them will crash you computer.
  162. (trap D in the driver) Don't tell me I didn't warn you.
  163.  
  164. If you have any suggestions, bug reports or questions, feel free to mail me.
  165. I'd also appreciate mails from people using it, so I can decide whether it's
  166. useful to continue enhancing the interface.
  167.  
  168. Enjoy your programming adventure in the world of REAL operating systems. 
  169.  
  170. Sander van Leeuwen
  171. email: s509475@dutiws.twi.tudelft.nl
  172.  
  173. ********************************************************************************
  174.             Standard Disclaimer
  175. ********************************************************************************
  176. This code is provided as is. The author (Sander van Leeuwen) isn't responsible
  177. for any damage that may result from using this code. 
  178. So don't mail me with claims about damaged ears/stereo's or crashed computers.
  179. ********************************************************************************
  180. ********************************************************************************        
  181.  
  182.