home *** CD-ROM | disk | FTP | other *** search
/ Audio 4.94 - Over 11,000 Files / audio-11000.iso / msdos / sndbords / proaudio / pcmtools / pcmtools.arj / LOADPCM.ARJ / PCM.DOC < prev    next >
Text File  |  1992-08-27  |  8KB  |  232 lines
  1. PCM - TSR Providing PCM Access
  2.  
  3.  
  4. Syntax
  5.  
  6.     pcm
  7.  
  8.  
  9. Options
  10.  
  11.     None
  12.  
  13.  
  14. Operation
  15.  
  16. Run the TSR "pcm.com" in order to provide access to PCM functions via
  17. interrupt 94h.  The program intercepts interrupt 9 in order to hot-key
  18. background sound play.
  19.  
  20. Although programming by linking to the static libraries is simple, 
  21. this TSR provides additional functionality:
  22.  
  23.     during load, the Hardware State Table is initialized.
  24.     retrieve the address of the DMA buffer (if set)
  25.     perform all initialization automatically (Function 8004)
  26.     perform custom initialization automatically (Function 8011)
  27.     internal User Functions 
  28.     background sound play using extended memory
  29.  
  30. Use "setdma.exe" to fix an area of memory for DMA transfers.  
  31. Programmers may want to alter "setdma" to access UMB's so the DMA
  32. buffer is completely out of conventional memory.
  33.  
  34. Use of the interrupt 94h interface is similar to that for "fm.com".
  35.  
  36.     Entry
  37.  
  38.     si    = function number
  39.     es:bx    = points to data buffer specific to function
  40.  
  41.     Exit
  42.     ax    = return integer or boolean value
  43.     dx:ax    = return long value or far address 
  44.  
  45. Note: this document and its associated programs are subject to change
  46. at any time and is being distributed for informational purposes only.
  47.  
  48. Example in C - set "testpcm.c"
  49.  
  50. Functions
  51.  
  52.     Description of Function
  53.    SI    ES:BX points to Buffer Containing...
  54.     Returned in AX (int) or DX:AX (void far *)
  55.     
  56.  
  57.     0    InitMVSound() - initialize the Hardware State Table
  58.         N/A
  59.     char far *    NULL if failed, else Hardware State Table address
  60.         
  61.        
  62.     1    InitPCM() - initialize PCM State Tables
  63.         N/A
  64.     int         0 if failed, else Library Version Number
  65.        
  66.     2    PCMInfo() - set samplerate and mono/stereo
  67.         struct pcminfo {long samplerate;  int stereoflag}; 
  68.     int        0 if okay, -1 if Samplerate Out of Range
  69.        
  70.     3    DMABuffer() - set DMA buffer address, size and partitions
  71.         struct dmabuf {char far * dmabuf, int bufkbsize, partitions;};
  72.     char far *    NULL if failed, else succeeded
  73.        
  74.     4    UserFunc() - set up callback routine for DMA interrupts
  75.         void far (*userfunction)();
  76.     void far *    NULL if failed, else succeeded
  77.        
  78.     5    PCMPlay() - play 
  79.         N/A
  80.     int        0 if successful, else failed
  81.        
  82.     6    PCMRecord() - record
  83.         N/A
  84.     int        0 if successful, else failed
  85.  
  86.     7    PausePCM() - pause playback or record
  87.         N/A
  88.     N/A
  89.  
  90.     8    ResumePCM() - resume paused playback or record
  91.         N/A
  92.     N/A
  93.  
  94.     9    StopPCM() - stop playback or record
  95.         N/A
  96.     N/A
  97.  
  98.     A    RemovePCM() - remove PCM hook to IRQ, clear internal DMA vars
  99.         N/A
  100.     N/A
  101.  
  102.     C    FindDMABuffer() - find area from memory within 64K block
  103.         struct fdmabuf {char huge *dmabuf; int bufkbsize};
  104.     char far *dmabuf    NULL if failed, else Valid DMA address
  105.  
  106.  8000     Retrieve Current DMA Address
  107.     N/A
  108.     char far *dmabuf    NULL if none, else Current DMA address
  109.  
  110.  8001     Retrieve Current DMA Size and Divisions
  111.     N/A
  112.     AX= Current DMA Size, DX= Current DMA Divisions
  113.  
  114.  8004     Make Ready For Play Mono at 11025Hz using B000:0 as 32K/2 DMA Buffer
  115.     N/A
  116.     N/A
  117.  
  118.  8011    Make Ready For Play using User Specified Parameters
  119.     struct pcmstate *{};    All Parms for PCMInfo, DMABuffer, UserFunc
  120.     struct pcmstate *{};    See Below for structure definition
  121.  
  122.  8012    Load Sound for Background Play
  123.     struct extstate *{};     All Parms for sound and access to XMS 
  124.     N/A
  125.  
  126.  8013    Return Bitfield Describing Background Sound Slot Usage
  127.     N/A
  128.     ax= bitfield of sounds used, dx= max sound slots (8)
  129.  
  130.  8014    Fill Structure for Specified Sound Slot
  131.     struct extstate *{};     desired sound number in field member
  132.     struct extstate *{};    structure filled with internal info
  133.  
  134.  8015    Set/Get/Unset Internal DMA Buffer
  135.     struct dmabuf *{};    if dmaoff != -1, set internal to contents
  136.     struct dmabuf *{};    if dmaoff == -1, set contents to internal
  137.  
  138.  8016    Simulate LeftShift-RightShift-# Keystroke
  139.     ax= 1 through 8        desired slot #
  140.     N/A
  141.  
  142.  
  143.  
  144.  
  145. Parameter Definitions
  146.  
  147. The "pcminfo" structure holds the Sample Rate and Mono/Stereo Flag.  
  148. The Sample Rate can vary from 100 to 88200 Hz Mono output, or 200 to 
  149. 44100 Hz for Stereo.
  150.  
  151. struct pcminfo            /* Passed to PCMInfo() */
  152. {
  153.     long samplerate;    /* 100 - 88200 (100 - 44100 for stereo) */
  154.     int stereoflag;        /* 0 = mono, 1 = stereo */
  155. };
  156.  
  157. The "dmabuf" structure contains the address of memory to be used as
  158. the DMA Load/Unload Buffer, the Size of this Buffer in KB, and the 
  159. Number of Partitions it is to be split into.  This buffer must not wrap
  160. around a 64KB block (the address should never get to ????:FFFF+ 1).
  161.  
  162. struct dmabuf            /* Passed to DMABuffer() */
  163. {
  164.     char far *dmabuf;    /* address of DMA buffer */
  165.     int bufkbsize;        /* size of DMA buffer in KB */
  166.     int partitions;        /* number of partitions */
  167. };
  168.  
  169. The "fdmabuf" structure contains a "huge" pointer to an area of memory
  170. that is at least twice as large as the associated "kbsize" parameter, 
  171. which specifies the desired size of memory in KB.
  172.  
  173. struct fdmabuf            /* Passed to FindDMABuffer() */
  174. {
  175.     char huge *dmabuf;    /* address of memory allocated */
  176.     int bufkbsize;        /* size of memory in KB */
  177. };
  178.  
  179. The "userfunc" parameter is the address of a routine that is to be
  180. called every time the PCM hardware has completed the output/input 
  181. of a partition of the DMA buffer.  Typically this routine decrements 
  182. a "flag" (see pcmstate.stat, below) which is monitored in the main
  183. program, allowing it to read/write data during PCM playback/record.
  184.  
  185. void (far *userfunc)();        /* address of callback routine 
  186.  
  187. The "pcmstate" structure is used to completely initialize the DMA and PCM
  188. state with user-supplied parameters, and includes space for the return
  189. values as well as a default DMA interrupt function that decrements the
  190. int pointed to by pcmstate.stat, and one that reads/writes files in the 
  191. background using the pcmstate.fh file handle.
  192.  
  193. struct pcmstate
  194. {
  195.    char far *f00r;     /* hardware state table returned from InitMVSound */
  196.    int f01r;         /* library code version returned from InitPCM */
  197.    long f02c1;         /* samplerate passed to PCMInfo */
  198.    int f02c2;         /* mono/stero flag passed to PCMInfo */
  199.    int f02r;         /* -1 returned by PCMInfo if error, else (?) */
  200.    void (far *f04c)();    /* address of interrupt function or index to internals */
  201.    void far *f04r;         /* 0 returned by UserFunc if error, else (?) */
  202.    char huge *f11c1;    /* not used at present FindDMABuffer */
  203.    int f11c2;         /* not used at present FindDMABuffer */
  204.    void far *f11r;         /* not used at present FindDMABuffer */
  205.    char far *f03c1;    /* DMA buffer passed to DMABuffer */
  206.    int f03c2;         /* size of DMA buffer in kilobytes passed to DMABuffer */
  207.    int f03c3;         /* number of partitions of DMA buffer passed to DMABuffer */
  208.    char far *f03r;     /* 0 returned by DMABuffer if error, else (?) */
  209.    int f10r;         /* returned by RemovePCM */
  210.    int f05r;         /* returned by PCMPlay */
  211.    int f07r;         /* returned by PausePCM */
  212.    int far *stat;     /* "volatile int" address decremented each DMA pass */
  213.    int fh    ;     /* file handle for input/output file (not implemented) */
  214.    int sbsize;         /* calculated size of each partition in bytes */
  215. };
  216.  
  217. struct extstate
  218. {
  219.    uint snum;    /* sound slot number */
  220.    uint xmsh;    /* XMS handle */
  221.    ulong xmss;    /* XMS memory size */
  222.    ulong rate;     /* samplerate of sound */
  223.    uint chan;    /* number of sound channels */
  224.    uint comp;    /* code for compression */
  225.    uint dsiz;    /* bitsize of sample data */
  226. };   
  227.  
  228.  
  229. Copyright (c) 1992.  Media Vision, Inc.  All Rights Reserved. 
  230. Programmer: Bart Crane
  231.  
  232.