home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / QBAS / RUKQ10.ZIP / RUCKDAC.DOC < prev    next >
Text File  |  1993-02-15  |  108KB  |  4,225 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.      RUCKUS-DAC Copyright (C)1993 Cornel Huth
  8.      Documentation Copyright (C)1993 Cornel Huth
  9.      All Rights Reserved.
  10.  
  11.      Version 1.00.
  12.  
  13.      For ordering information, license agreement, and product support
  14.      information, see Appendix Z.
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.      Introduction
  74.  
  75.      RUCKUS-DAC is one part of the RUCKUS sound toolkit for DOS programmers. Its
  76.      forte is its ability to play digital data in three different formats and
  77.      record in two: VOC, WAVE, and MOD. The other part of the RUCKUS sound
  78.      toolkit is RUCKUS-MIDI. Its forte is its ability to play standard MIDI data
  79.      files. See RUCKUS-MIDI for more.
  80.  
  81.      RUCKUS-DAC currently supports six sound devices: the PC speaker, a DAC on
  82.      an LPT port, Disney Sound Source, AdLib MSC, Sound Blaster, and the Sound
  83.      Blaster Pro (stereo). Since most sound devices emulate one of the above,
  84.      RUCKUS-DAC should handle most devices likely to be found in a PC. RUCKUS-
  85.      DAC is implemented to be device-independent. As new sound hardware (with
  86.      supporting documentation) becomes available to this programmer, it will be
  87.      added. The code you write to play any of the digital formats using RUCKUS
  88.      will play on any new device added later without any code changes to your
  89.      program. You just supply the new device ID (see InitDac for more). 
  90.  
  91.      The RUCKUS toolkit supports most DOS compilers as is. This documentation
  92.      describes using RUCKUS with BASIC DOS compilers. Also available is a C-
  93.      specific version of this documentation. Other implementations should be
  94.      able to get the necessary details using this documentation. Note that these
  95.      toolkits will not work with the current or past Turbo Pascal compilers.
  96.      This is due to Turbo Pascal's proprietary linkage methods.
  97.  
  98.      To provide compiler-independence, RUCKUS (and all of my latest toolkits)
  99.      implements a simple calling scheme: a single far pointer (segmented) is
  100.      passed to RUCKUS. The data structure that is pointed to varies depending on
  101.      RUCKUS function. There are 13 structure types ("packs") currently. The
  102.      first two data members of each pack are identical in all packs. These are
  103.      Func and Stat. The remaining members, if any, vary depending on
  104.      requirements. For instance, the LoadDac routine uses, in addition to Func
  105.      and Stat, six additional members: FilenamePtr, StartPos, LoadSize, XMMflag,
  106.      XMMhandle and LoadPtr. The steps needed to load a digital (LoadDac is for
  107.      VOC/WAVE files, LoadMod is for MOD files) data file to memory would be as
  108.      follows:
  109.  
  110.  
  111.           1. Allocate pack. Packs are reusable and can be allocated any way you
  112.           want. Here we make a static allocation for simplicity.
  113.  
  114.           DIM LP AS LoadPackTYPE
  115.  
  116.           2. Assign member values:
  117.       
  118.           filenameZ$ = file$ + CHR$(0)  'must terminate string with 0
  119.           LP.Func = LoadMidi
  120.           LP.FilenamePtr = SADD(filenameZ$)  
  121.           LP.FilenamePtrSeg = VARSEG(filenameZ$)
  122.           'LP.FilenamePtrSeg = SSEG(filenameZ$)  'for BASIC7/VBDOS
  123.           LP.StartPos = 0&                    
  124.           LP.LoadSize = 0&
  125.           LP.XMMflag = 0   
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.           3. Call RUCKUS:
  140.  
  141.           stat = RUCKDAC(LP)
  142.  
  143.           4. On return from the call:
  144.  
  145.           IF stat = 0 THEN 
  146.              ' LP.LoadPtr -> address of digital data in memory
  147.              'or, if XMMflag then LP.XMMhandle = XMS handle of storage 
  148.  
  149.      After the load you can immediately call the PlayDac routine using the
  150.      LP.LoadPtr returned from the LoadDac call. You don't need to use the RUCKUS
  151.      LoadDac routine; you can perform your own digital data file loads to memory
  152.      (VOC and WAV only, MODs must be loaded by RUCKUS-DAC). However, RUCKUS can
  153.      load up to 32 separate digital files at one time (and 96 more to XMS) and
  154.      performs all the necessary memory allocations and deallocations
  155.      automatically. See LoadDac/LoadMod for more.
  156.  
  157.      As you can see, using RUCKUS is easy. If you'd rather use a traditional 
  158.      calling convention, wrap the RUCKUS routines in a BASIC function and call
  159.      it as you normally would, i.e., stat = LoadDacFile(file$,LP) where
  160.      LoadDacFile contains the actual code (as shown above).
  161.  
  162.      Now that I have your interest, let me tell you why I've provided this
  163.      toolkit for you. Shareware. That's right. Shareware. What I've done is
  164.      provide you with a means to evaluate this product completely, with no
  165.      upfront obligations. If you can't make use of this product, no problem.
  166.      Think of this as the ultimate return policy. You can actually take the
  167.      goods home, try it out, break it in. Then, if after a period of no more
  168.      than 21 days, you feel that this product is well worth the price I'm
  169.      asking, by all means, you should go ahead and fill out the order form and
  170.      send it in. If you do not register, then of course, it means the product is
  171.      not something you can use. If you can't use it, I don't want your money.
  172.      But if it's something you will use, it's only fair that you register. The
  173.      PROFESSIONAL registered versions does not have any built-in advertising
  174.      screens. The PERSONAL DEVELOPER registered version does display a sign-on
  175.      banner once. See Appendix Z. for ordering options and other related
  176.      information specific to this product.
  177.  
  178.      The documentation that follows describes each of the function routines as
  179.      to use, pack type used, and sample code in BASIC. Also available is a C
  180.      version of this toolkit, differing only in example programs and
  181.      documentation*. For additional source examples see the included X files on
  182.      disk.
  183.  
  184.      *There is a specific object module that must be used with any Borland C
  185.      compiler, but this LIB will work for other C compilers.
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.      RUCKUS-DAC Functions.
  206.  
  207.       0. SysInfoDac  ...........................................  5
  208.       1. InitDac  ..............................................  7
  209.       2. ExitDac  ..............................................  8
  210.       3. AtExitDac  ............................................  9
  211.       4. LoadDac  .............................................. 10
  212.       5. PlayDac  .............................................. 12
  213.       6. RecordDac  ............................................ 13
  214.       7. StoreDac  ............................................. 15
  215.       8. EndDac  ............................................... 16
  216.       9. PauseDac  ............................................. 17
  217.      10. DeallocDac  ........................................... 18
  218.          11 to 19 are not used 
  219.      20. SetAllDac  ............................................ 19 
  220.      21. SetVolumeDac  ......................................... 21
  221.      22. SetIntRateDac  ........................................ 22
  222.      23. SetPriorityDac  ....................................... 23
  223.          24 to 27 are not used
  224.      28. GetBufferDataDac  ..................................... 24
  225.      29. GetBytePosDac  ........................................ 25
  226.      30. SetAllSBP  ............................................ 26
  227.      31. SetVolMainSBP ......................................... 28
  228.      32. SetVolVocSBP  ......................................... 29
  229.      33. SetLevelMicSBP  ....................................... 30
  230.      34. SetLevelCDSBP   ....................................... 31
  231.      35. SetLevelLineSBP  ...................................... 32
  232.      36. SetFilterOutSBP  ...................................... 33
  233.      37. SetFilterInSBP  ....................................... 34
  234.      38. SetSourceSBP  ......................................... 35
  235.      39. SetStereoSBP  ......................................... 36
  236.      40. SetSpeakerSB  ......................................... 37
  237.          41 to 47 are not used
  238.      48. GetMixerRegSBP  ....................................... 38
  239.      49. GetDacSB .............................................. 39
  240.      50. ExitMod  .............................................. 40
  241.      51. AtExitMod  ............................................ 41
  242.      52. LoadMod  .............................................. 42
  243.      53. PlayMod  .............................................. 43
  244.      54. EndMod  ............................................... 44
  245.      55. PauseMod  ............................................. 45
  246.      56. SetIntRateMod ......................................... 46
  247.      57. SetSpeedMod ........................................... 47
  248.      58. SetVolumeMod  ......................................... 48
  249.      59. SetPositionMod ........................................ 49
  250.      60. SetStereoMod .......................................... 50
  251.      61. SetFastMod ............................................ 51
  252.          Appendix A. Tips and Tricks ........................... 52
  253.          Appendix B. Pack Structure ............................ 53
  254.          Appendix C. Compiler, Linker, QLB, and Call Use ....... 58
  255.          Appendix D. RUCKUS-DAC Data Area ...................... 60
  256.          Appendix Z. Ordering Information, License Agreement
  257.                      and Product Support........................ 62
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.      SysInfoDac          Func: 0        Pack: SysInfoPack
  272.  
  273.      Before doing any other RUCKUS function, you should call SysInfoDac to
  274.      determine what sound devices are available. RUCKUS-DAC currently supports
  275.      the following devices:
  276.  
  277.           0. PC speaker
  278.           1. LPT-DAC device on a printer port, commonly home-built
  279.           2. Disney Sound Source, a printer port DAC device
  280.           3. AdLib Music Synthesizer Card
  281.           4. Sound Blaster (DSP version 1.03 and up)
  282.           5. Sound Blaster Pro
  283.           6. UltraSound*
  284.  
  285.      *The UltraSound (GUS) will be supported in the next release.
  286.  
  287.      Since many current sound cards are Sound Blaster compatible, RUCKUS-DAC
  288.      supports somewhere around 95% of all sound devices in active use on PC-
  289.      compatible computers.
  290.  
  291.      SysInfoDac scans for and detects all devices. In the case of the DAC on the
  292.      printer port (LPT-DAC), it can only detect if a printer port is available.
  293.      All other sound cards are detected by their manufacturer's documented
  294.      methods, and should be 100% reliable. Information returned includes the
  295.      device's base port address, IRQ line, DMA channel, and capabilities.
  296.  
  297.      Since the SB Pro is SB-compatible, and since the SB is AdLib-compatible,
  298.      these lower devices are also detected in these cards.
  299.  
  300.  
  301.      Sample Use (QuickBASIC 4.5):
  302.  
  303.      DIM SIP AS SysInfoPackTYPE
  304.  
  305.      SIP.Func = SysInfoDac    'SysInfoDac is a CONST in RUCKDAC.BI
  306.      stat = RUCKDAC(SIP)      'call to RUCKUS library code
  307.      IF stat = 0 THEN
  308.         PRINT "CPU type is "; SIP.CPU
  309.         PRINT "MHz (approx)"; SIP.MHZ
  310.         IF SIP.Device5 THEN PRINT "SB PRO at port ";HEX$(SIP.D5port)
  311.         IF SIP.Device4 THEN PRINT "SB 1.5 at port ";HEX$(SIP.D4port)
  312.         IF SIP.Device3 THEN PRINT "AdLib at port ";HEX$(SIP.D3port)
  313.         IF SIP.Device2 THEN PRINT "Disney at port ";HEX$(SIP.D2port)
  314.         IF SIP.Device1 THEN PRINT "LPT-DAC at port ";HEX$(SIP.D1port)
  315.         PRINT "PC speaker always available"
  316.      ENDIF
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                                                                5
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.      Sample Use (BASIC 7.1/ VBDOS):
  338.  
  339.  
  340.      NOTE: THE ONLY DIFFERENCE IN USING BASIC 7.1 WITH REGARD TO RUCKUS
  341.            IS THE METHOD OF GETTING A STRING'S ADDRESS. FOR QUICKBASIC, 
  342.            USE VARSEG/SADD. WITH BASIC 7.1 OR VBDOS, USE SSEG/SADD.
  343.  
  344.  
  345.      Since BASIC7 allows arrays in TYPE variables, we use that feature to
  346.      simplify the variable. You can use the other TYPE variable if you want, but
  347.      this way seems more versatile to me. To use the SysInfoPackTYPE7 you must
  348.      uncomment-out the definition in the RUCKDAC.BI file.
  349.  
  350.      DIM SIP AS SysInfoPackTYPE7  'NOTE the 7 at the end
  351.  
  352.      SIP.Func = SysInfoDac    'SysInfoDac is a CONST in RUCKDAC.BI
  353.      stat = RUCKDAC(SIP)      'call to RUCKUS library code
  354.      IF stat = 0 THEN
  355.         PRINT "CPU type is "; SIP.CPU
  356.         PRINT "MHz (approx)"; SIP.MHZ
  357.         FOR i = 5 TO 1
  358.            IF SIP.SD(i).device THEN
  359.               SELECT CASE i
  360.               CASE 5: PRINT "SB PRO at port ";HEX$(SIP.SD(5).port)
  361.               CASE 4: PRINT "SB 1.5 at port ";HEX$(SIP.SD(4).port)
  362.               CASE 3: PRINT "AdLib at port ";HEX$(SIP.SD(3).port)
  363.               CASE 2: PRINT "Disney at port ";HEX$(SIP.SD(2).port)
  364.               CASE 1: PRINT "LPT-DAC at port ";HEX$(SIP.SD(1).port)
  365.            ENDIF
  366.         NEXT   
  367.         PRINT "PC speaker always available"
  368.      ENDIF
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                                                                6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.      InitDac             Func: 1        Pack: InitPack
  404.  
  405.      Before you can use a sound device, you must inform RUCKUS about it. The
  406.      InitDac routine sets up default sets of data that RUCKUS uses, or that you
  407.      can later change. You cannot operate a device until you have called this
  408.      routine. You should not InitDac more than one sound device at a time. If
  409.      you want to use a different device, first ExitDac then InitDac again.
  410.  
  411.      The information that InitDac requires is available from the SysInfoDac
  412.      routine. InitDac returns with information on its data section address and
  413.      size, and the address of the ExitDac routine (in case AtExitDac doesn't
  414.      work for your esoteric compiler or run-time library).
  415.  
  416.      InitDac is used for both RUCKUS-DAC and the RUCKUS-DAC mod extension code.
  417.  
  418.      There is a special feature available for the PC speaker and the AdLib
  419.      devices: 2x upsampling. To use 2x upsampling, use the I/O port as returned
  420.      by SysInfoDac for IP.IOport. To use standard (in some cases downsampling)
  421.      play for the PC speaker and AdLib (recommended for play of samples with
  422.      rates above 8kHz) use an IP.IOport=0. For an example of 2x upsampling see
  423.      the MODAC1 documentation. Upsampling is available only for VOC and WAVE
  424.      playback.
  425.  
  426.  
  427.      Sample Use:
  428.  
  429.      DIM IP AS InitPackTYPE   'in RUCKDAC.BI
  430.  
  431.      IP.Func = InitDac        'CONST in RUCKDAC.BI
  432.      IP.DeviceID = device     'see SysInfoDac for device numbers
  433.      IP.IOport = port         'and other info needed by InitDac
  434.      IP.IRQline = IRQ
  435.      IP.DMAch = DMA
  436.      stat = RUCKDAC(IP)
  437.      IF stat = 0 THEN         'device initialized okay
  438.  
  439.         'By using the pointer returned by InitDac, we can check on any
  440.         'RUCKUS-DAC data value (fully documented in DACDATA.DOC) fast
  441.         'DEF & PEEKing are much faster than separate function calls 
  442.         
  443.         DEF SEG = IP.InfoPtrSeg
  444.         DacEnd = PEEK(IP.InfoPtrOff + 10) 'since nothing is playing this=1
  445.         DEF SEG
  446.      ENDIF
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.                                                                                7
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.      ExitDac             Func: 2        Pack: XitPack
  470.  
  471.      When using RUCKUS, certain aspects of the computer are controlled by the
  472.      RUCKUS code. To have RUCKUS return full control back to the computer and
  473.      operating system, ExitDac must be called. To ensure that this happens, even
  474.      after an abnormal termination (such as an untrapped divide by zero), RUCKUS
  475.      provides a routine that ensures that ExitDac is always called before your
  476.      application ends. See AtExitDac for more.
  477.  
  478.      Once a sound device has been initialized with InitDac, you must call
  479.      ExitDac before you can switch to another device with InitDac. Calling
  480.      ExitDac releases any memory allocations made while the previous sound
  481.      device was active (allocations made by LoadDac, LoadMod, or RecordDac).
  482.      Memory allocations that your program has made on its own are not affected.
  483.  
  484.      Tip: If you call InitDac with one device, load a file, then call InitDac
  485.      again with another device, the memory allocated by the load is not
  486.      released. This allows you to play data from previous load operation(s) on
  487.      all the RUCKUS-supported devices. To force the release of a previous memory
  488.      allocation, see DeallocDac.
  489.  
  490.  
  491.      Sample Use:
  492.  
  493.      DIM XP AS ExitPackTYPE
  494.  
  495.      XP.Func = ExitDac
  496.      stat = RUCKDAC(XP)
  497.      IF stat THEN 'error
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                                                                                8
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.      AtExitDac           Func: 3        Pack: XitPack
  536.  
  537.      To ensure that all machine control is returned to the operating system and
  538.      that all RUCKUS-made memory allocations are released before your
  539.      application program ends, AtExitDac should be used. This routine takes
  540.      advantage of most compiler's _atexit enregistration routine. This _atexit
  541.      compiler run-time library routine allows for up to 32 different calls to be
  542.      made just prior to it (the compiler's run-time code) returning to the
  543.      operating system (program termination). Most of the time, you can make all
  544.      the necessary shutdowns that your program requires in your app's code.
  545.      However, abnormal terminations -- terminations that can cause a bypass of
  546.      your own shutdown code -- may mean that when the operating systems regains
  547.      control, certain machine operations are not in a stable state. The
  548.      AtExitDac routine ensures that ExitDac is called no matter what (in most
  549.      all cases, except where the program locks up, in which case the session
  550.      needs to be reset anyway). 
  551.  
  552.      Note: AtExitDac should be called only once in your program's execution. 
  553.  
  554.      Graphically, your program executes like this:
  555.  
  556.         DOS C>program.exe
  557.           |
  558.         Compiler startup code (performs basic setup)
  559.           |
  560.           +----->+
  561.                  | Your program starts, ends
  562.           +<-----+
  563.           |   
  564.          rest of startup code, _atexit registered routines
  565.           |
  566.          DOS C>_
  567.  
  568.      Caution: In order for the _atexit registered routines to be called by your
  569.      compilers run-time, you must not allow you program to exit via non-standard
  570.      ways. Calling INT21/4C is on example (you should never do this from
  571.      compiled code, anyway).
  572.  
  573.      The startup code is basically a program that sets up your program to run,
  574.      calls your program, regains control when your program ends, then performs
  575.      the necessary shutdown actions required, including calling all routines
  576.      registered with _atexit.
  577.  
  578.      Sample Use:
  579.  
  580.      DIM XP AS ExitPack
  581.  
  582.      XP.Func = AtExitDac
  583.      stat = RUCKDAC(XP)
  584.      IF stat THEN PRINT "_atexit is full (more than 32 calls made to _atexit)"
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                                                                9
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.      LoadDac             Func: 4        Pack: LoadPack
  602.  
  603.      Though not required, you can have RUCKUS load a digital file into memory
  604.      for you. It makes the necessary memory allocations and loads the data into
  605.      conventional or XMS memory. You can load up to 32 separate digital data
  606.      files to conventional memory at one time, and up to 96 more into XMS.
  607.      RUCKUS takes care of the memory allocation details.
  608.  
  609.      LoadDac can also be instructed to start loading at any particular byte in a
  610.      file for as many bytes as you specify. This would be useful, for example,
  611.      if you have a single file made up of several VOC or WAVE files appended to
  612.      form one large data file.
  613.  
  614.      Sample Use:
  615.  
  616.      DIM LP AS LoadPackTYPE
  617.  
  618.      nix& = SETMEM(700000)
  619.      mem& = SETMEM(0)
  620.      IF YouWillBeUsingConventionalMemory THEN
  621.         nix& = SETMEM(mem& - 2100) 'release all but 2K to the OS
  622.                                    'or as much as needed to store file
  623.      ELSE
  624.         nix& = SETMEM(-66000)      'release 64K for temp RUCKUS use
  625.                                    'until after the load into XMS
  626.      ENDIF
  627.      LP.Func = LoadDac
  628.      LP.FilenamePtrOff = SADD(filename$)
  629.      LP.FilenamePtrSeg = VARSEG(filename$)
  630.       'BASIC7 use:
  631.       'LP.FilenamePtrOff = SADD(filename$)
  632.       'LP.FilenamePtrSeg = SSEG(filename$)
  633.      LP.StartPos = 0&   'start load at first byte of file
  634.      LP.LoadSize = 0&   'have RUCKUS load all of it
  635.      LP.XMMflag = 0     '-1 if loading into XMS
  636.      stat = RUCKDAC(LP)
  637.      IF stat = 0 THEN
  638.         If YouWillBeUsingConventionalMemory THEN
  639.            ThisDataLoadOff = LP.LoadPtrOff   'needed for later PlayDac
  640.            ThisDataLoadSeg = LP.LoadPtrSeg   
  641.            nix& = SETMEM(700000) 
  642.         ELSE
  643.            ThisDataXMShandle = LP.XMMhandle
  644.            nix& = SETMEM(66000)  'return the 64K to BASIC
  645.         ENDIF
  646.      ELSE
  647.         nix& = SETMEM(700000)  '700,000 tells BASIC to reclaim unused memory
  648.         'file load error in stat
  649.      ENDIF
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.                                                                               10
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.      'See how much memory was used by this _particular_ load, in K,
  668.      'and how much conventional and XMS memory remain
  669.  
  670.      DEF SEG = IP.InfoPtrSeg    'IP.InfoPtrSeg returned from InitDac call
  671.      bp = IP.InfoPtrOff         'assign to make typing shorter
  672.      Kused = (256 * PEEK(bp + 23)) + PEEK(bp + 22)
  673.      Kdos = (256 * PEEK(bp + 17)) + PEEK(bp + 16)
  674.      KXMS = (256 * PEEK(bp + 19)) + PEEK(bp + 18)
  675.      DEF SEG
  676.  
  677.      'If you dislike DEF SEG=/PEEKs then just wrap up the RUCKUS data gets in
  678.      'a separate FUNCTION. See the DATALIST.DOC file for more. The above method,
  679.      'however, is as fast as it gets. Note that it may be possible to have more
  680.      'than 32767K of XMS (32M) so you may want to define KXMS as LONG and use a
  681.      '256& in the equation.
  682.  
  683.      Note that even though loading into XMS memory, RUCKUS-DAC still needs some
  684.      conventional memory to use as a buffer. After the load to XMS, the low
  685.      memory is no longer required.
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.                                                                               11
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.      PlayDac             Func: 5        Pack: PlaybackPack
  734.  
  735.      Once the digital data is in either conventional or XMS memory, you can play
  736.      it to any of the RUCKUS-supported devices. XMS memory, however, requires
  737.      DMA playback mode; this mode is supported in the Sound Blasters only. Also,
  738.      for STEREO playback, DMA mode is required (SB Pro only).
  739.  
  740.      In addition to DMA-mode playback, you can instruct RUCKUS to play in the
  741.      background or foreground. Playing in the background allows your computer
  742.      program to regain control immediately after play has begun. If you choose
  743.      foreground play, control does not return to your program until the end of
  744.      the data has been played, or, until CTRL-ALT is pressed.
  745.  
  746.      All RUCKUS-supported devices can be played in the background. Only the
  747.      Sound Blasters can be played using DMA. DMA playback is similar to
  748.      background play in that control is returned to your program immediately,
  749.      but it is also much more efficient since DMA playback uses no CPU time.
  750.      Background play, on the other hand, can require anywhere from 1 to 100% of
  751.      available CPU time, depending on what playback rate has been selected (see
  752.      SetIntRateDac). 
  753.  
  754.      Since it's possible to load several data files into memory at one time, to
  755.      play a particular data file requires that you specify its start address or,
  756.      if loaded to XMS memory, its XMS handle. Given the code sequence example in
  757.      LoadDac, the following PlayDac code takes up from there:
  758.  
  759.      DIM PBP AS PlaybackPackTYPE
  760.  
  761.      PBP.Func = PlayDac
  762.      PBP.Mode = 2        'mode 0=foreground, 1=background, 2=DMA
  763.      PBP.XMMhandle = 0   '0=conventional memory data follow, 1+=XMS data follows
  764.  
  765.      'If conventional memory used, then the following pointer is the 
  766.      'segment:offset start address of the VOC/WAVE data to play.
  767.      '
  768.      'If XMS memory used, the following pointer is the 32-bit offset within the
  769.      'XMS handle (PBP.XMMhandle) that the data starts. If you just load one data
  770.      'file to one XMM handle, then these will always=0. However, if you're short
  771.      'on available XMM handles, you could load several data files into a single,
  772.      'huge, XMM allocation. In order to do this, you must do your own data
  773.      'loads since LoadDac loads one file per XMM handle.
  774.      '
  775.      PBP.LoadPtrOff = LP.LoadPtrPOff
  776.      PBP.LoadPtrSeg = LP.LoadPtrSeg
  777.  
  778.      'Note: the PBP.BufferSize is used by PlayMod only. Also, you may want/need
  779.      'to perform pre-Play tasks. See SetAllDac/SetAllSBP.
  780.  
  781.      stat = RUCKDAC(PBP)
  782.      IF stat = 0 THEN
  783.         'if DMA or background mode then the digital data is playing now, 
  784.         'but if foreground mode, the play has ended by the time we get here
  785.      ELSE
  786.         'play error
  787.  
  788.                                                                               12
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.      RecordDac           Func: 6        Pack: RecordPack
  800.  
  801.      The Sound Blasters can record as well as play digital data. As with play,
  802.      you can record directly into conventional or XMS memory. You can let RUCKUS
  803.      make the memory allocations, or you can allocate your own memory and record
  804.      into that. With the SB Pro, you can also record in stereo.
  805.  
  806.      With the Sound Blaster Pro you can select among three input sources: mic,
  807.      line, and CD. The earlier Sound Blaster has one input, the mic. A quality
  808.      microphone can make a big difference. For other-than-mic input on the SB,
  809.      you can pipe the headphone output of a CD player into the mic input. Your
  810.      results may vary, but this is better than mic'ing a loudspeaker. For
  811.      anything other than mic input, the SB Pro is recommended. Its recording
  812.      quality is very good since it allows sampling rates up to 45.5kHz in mono,
  813.      and 22.75kHz in stereo. The SB allows recording sampling rates up to 12kHz
  814.      (rated to 13kHz record and 23kHz playback). The sampling size is 8 bits.
  815.  
  816.      NOTE: TO RECORD IN STEREO AT A GIVEN SAMPLE RATE, YOU MUST SPECIFY TWICE
  817.            THE RATE DESIRED. FOR EXAMPLE, TO RECORD OFF A CD DECK CONNECTED TO
  818.            THE LINE INPUT OF THE PRO, AT A SAMPLE RATE OF 22.5kHz, YOU MUST
  819.            SET THE SP.SetIntRate=44100 (BUT SEE THE sr= CALCULATION BELOW).
  820.  
  821.      Sample Use:
  822.  
  823.      DIM RP AS RecordPackTYPE
  824.  
  825.      DIM EP AS ExitPackTYPE     'needed for EndDac call below
  826.      EP.Func = EndDac           'preload EP.Func here for space reasons
  827.  
  828.      nix& = SETMEM(700000)  'we do this to return all previous SETMEMs
  829.      mem& = SETMEM(0)
  830.      IF YouWillBeUsingConventionalMemory THEN nix& = SETMEM(mem& - 2100)
  831.  
  832.      'let's see how much memory we have available in which to record
  833.  
  834.      DEF SEG = IP.InfoPtrSeg    
  835.      bp = IP.InfoPtrOff         
  836.      Kdos = (256 * PEEK(bp + 17)) + PEEK(bp + 16)
  837.      KXMS = (256 * PEEK(bp + 19)) + PEEK(bp + 18)
  838.      DEF SEG
  839.       
  840.      'Since RP.SampleRate is defined as an INTEGER we need to make an
  841.      'adjustment to sample rates > 32767. The following shows how to do
  842.      'this, given that the variable SampleToRecordAt& is the sample rate:
  843.  
  844.      IF SampleToRecordAt& > 32767 THEN
  845.         sr = SampleToRecordAt& - 65536 
  846.      ELSE
  847.         sr = SampleToRecordAt&
  848.      ENDIF
  849.      RP.Func = RecordDac
  850.      RP.SampleRate = sr
  851.  
  852.  
  853.  
  854.                                                                               13
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.      'To load into XMM and have RUCKUS make the allocation, set RP.XMMhandle
  866.      'to -1. If you made your own XMS allocation, set this to your handle.
  867.      'To load into conventional memory and have RUCKUS make the allocation,
  868.      'set RP.RecordPtrOff/Seg to 0. If you made your own allocation, set this
  869.      'to your segment:offset pointer.
  870.  
  871.      RP.XMMhandle = 0         'use conventional memory if this is 0
  872.      RP.RecordPtrOff = 0      'have RUCKUS make the memory allocation
  873.      RP.RecordPtrSeg = 0      'if this is 0 (and if RP.XMMhandle=0)
  874.  
  875.      'By using the Kdos or KXMS values above, we can record as many bytes
  876.      'as we have available. Below we reserve 5K for miscellaneous use, as
  877.      'you should, too. This is the max bytes to record; we can also stop
  878.      'at any point before this.
  879.  
  880.      RP.RecordBytes = (1024& * (Kdos - 5))  
  881.      RP.StereoFlag = 0
  882.      stat = RUCKDAC(RP)
  883.      IF stat = 0 THEN
  884.         'we are recording right now, using DMA, so, while we could do just
  885.         'about anything we wanted, in this example, we just wait until the
  886.         'record is over, or until we hit a key
  887.  
  888.         DEF SEG = IP.InfoPtrSeg
  889.         bp = IP.InfoPtrOff + 10   'point to the DacEnd RUCKUS data variable
  890.         DO 
  891.            akey = LEN(INKEY$)     'if a key pressed this becomes 1 or 2
  892.            bdone = PEEK(bp)       'if recording bytes done this becomes 1
  893.         LOOP UNTIL akey OR bdone
  894.         nix = RUCKDAC(EP)         'stop recording (EP defined/assigned above)
  895.  
  896.         'The above loop won't be exited until all the bytes requested have
  897.         'been recorded, or a key was pressed. Let's see exactly how many 
  898.         'bytes were recorded:
  899.  
  900.         bp = IP.InfoPtrOff + 36   'still using same DEF SEG = above 
  901.         byte0 = PEEK(bp)          'get 4 bytes of the double-word (LONG)
  902.         byte1 = PEEK(bp + 1)
  903.         byte2 = PEEK(bp + 2)      'unless you are recording more than 16MB,
  904.         'byte3 = PEEK(bp + 3)      'byte3 will always be 0
  905.  
  906.         RecBytes& = (65536 * byte2) + (256& * byte1) + byte0
  907.         DEF SEG
  908.      ENDIF
  909.  
  910.      'Now you can save the data by using StoreDac, or play it using PlayDac.
  911.      'On return from the RECORD, RP.RecordPtrSeg/Off is set to the
  912.      'segment:offset of the first byte recorded in conventional memory, or
  913.      'if using XMS memory, RP.XMMhandle is set to the XMS handle.
  914.  
  915.      Note: This data is preceded by the appropriate Sound Blaster block
  916.      header(s) but not with a VOC file header. To save the data to either a VOC
  917.      or WAVE file, use the StoreDac routine.
  918.  
  919.  
  920.                                                                               14
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.      StoreDac            Func: 7        Pack: SaveDataPack
  932.  
  933.      Once digital data has been loaded or recorded in memory, you can store it
  934.      do disk in either VOC or WAVE format. If you want, you can load a file in
  935.      one format and save it in the other with just a few lines of code (shown
  936.      below).
  937.  
  938.      Sample Use:
  939.  
  940.      DIM SDP AS SaveDataPackTYPE
  941.  
  942.      SDP.Func = StoreDac
  943.      SDP.FilenamePtrOff = SADD(filename$)
  944.      SDP.FilenamePtrSeg = VARSEG(filename$)
  945.       'BASIC7 use:
  946.       'SDP.FilenamePtrOff = SADD(filename$)
  947.       'SDP.FilenamePtrSeg = SSEG(filename$)
  948.  
  949.      'the LP pointer below is from (say) a just-loaded VOC file (using
  950.      'LoadDac), and we want to convert and store it to WAVE format
  951.  
  952.      SDP.DataPtrOff = LP.LoadPtrOff  'segment:offset of conventional memory
  953.      SDP.DataPtrSeg = LP.LoadPtrSeg  'or 0 if storing from an XMS handle
  954.      SDP.FileType = 2                '1=VOC, 2=WAVE
  955.      SDP.XMMhandle = 0               '0 if DOS data, else XMS handle 
  956.      stat = RUCKDAC(SDP)
  957.      IF stat = 0 THEN
  958.         'data stored to filename$
  959.      ELSE
  960.         'file save error in stat
  961.      ENDIF
  962.  
  963.      Caution: Be sure to account for the expanded memory required once data has
  964.      been stored to a file. StoreDac builds the appropriate VOC or WAV header
  965.      and this adds to the total memory required to reload. I suggest that you do
  966.      not record so much data as to not be able to load it back in once saved to
  967.      VOC or WAVE format.
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.                                                                               15
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.      EndDac              Func: 8        Pack: XitPack
  998.  
  999.      EndDac is used to end (stop) play or record on command. Once PlayDac has
  1000.      started, it continues to play in the background until either the end of the
  1001.      digital data has been reached, or you call this routine. In the case of a
  1002.      record, play continues until the number of bytes requested has been
  1003.      recorded, or this routine is called.
  1004.  
  1005.      Sample Use:
  1006.  
  1007.      DIM XP AS ExitPackTYPE
  1008.  
  1009.      'LoadDac and PlayDac, or RecordDac, have already been called
  1010.      'see those routines for more information
  1011.  
  1012.      XP.Func = EndDac      'if play or record is active this call
  1013.      stat = RUCKDAC(XP)    'ends it
  1014.  
  1015.      'See RecordDac on getting the number of bytes actually recorded
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.                                                                               16
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.      PauseDac            Func: 9        Pack: PausePack
  1064.  
  1065.      PauseDac allows you to temporarily pause and then restart a playback.
  1066.  
  1067.  
  1068.      Sample Use:
  1069.  
  1070.      DIM PP AS PausePackTYPE
  1071.  
  1072.      PP.Func = PauseDac
  1073.      PP.Pause = 1        'non-zero pauses, zero restarts
  1074.      stat = RUCKDAC(PP)
  1075.  
  1076.      PRINT "Press a key to continue playback"
  1077.      a$ = INPUT$(1)
  1078.  
  1079.      PP.Pause = 0
  1080.      stat = RUCKDAC(PP)  'continue playback
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.                                                                               17
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.      DeallocDac          Func: 10       Pack: DeallocPack
  1130.  
  1131.      If you have RUCKUS load digital data files, which is most likely the case,
  1132.      it makes memory allocations from the operating system memory pool. RUCKUS
  1133.      tracks up to 32 consecutive DOS loads, and up to 96 loads to XMS (provided
  1134.      enough memory and XMS handles). These should be higher than you'll ever
  1135.      likely use at one time. DeallocDac "unloads" files that RUCKUS has loaded,
  1136.      thus releasing the memory that they used. 
  1137.  
  1138.      As an example, let's say that you want to start up your program with 5
  1139.      digital data files in XMS memory. You have 5MB of XMS available. Each data
  1140.      file is 1M in size. To load a new data file after these 5, you will need to
  1141.      unload one of the 5 already loaded. DeallocDac does that for you. The
  1142.      following example loads a single data file to XMS then immediately unloads
  1143.      it.
  1144.  
  1145.      DeallocDac is not used for releasing LoadMod allocations. 
  1146.  
  1147.      Sample Use:
  1148.  
  1149.      DIM LP AS LoadPackTYPE
  1150.      DIM DP AS DeallocPackTYPE
  1151.  
  1152.      nix& = SETMEM(700000)
  1153.      nix& = SETMEM(-66000)      'release up to 64K for temp RUCKUS use
  1154.                                 'until after the load into XMS
  1155.      LP.Func = LoadDac
  1156.      LP.FilenamePtrOff = SADD(filename$)
  1157.      LP.FilenamePtrSeg = VARSEG(filename$)
  1158.       'BASIC7 use:
  1159.       'LP.FilenamePtrOff = SADD(filename$)
  1160.       'LP.FilenamePtrSeg = SSEG(filename$)
  1161.      LP.StartPos = 0&   
  1162.      LP.LoadSize = 0&   
  1163.      LP.XMMflag = 1        'non-zero means use XMS for load
  1164.      stat = RUCKDAC(LP)
  1165.  
  1166.      nix& = SETMEM(66000)  'return the 64K to BASIC
  1167.  
  1168.      IF stat = 0 THEN
  1169.         DP.Func = DeallocDac
  1170.         DP.HandSeg = LP.XMMhandle  'XMM handle returned by RUCKDAC(LP)
  1171.         DP.TypeFlag = LP.XMMflag   '0=DOS allocation, 1=XMS
  1172.         stat = RUCKDAC(DP)         '--if this were a DOS allocation, DP.HandSeg
  1173.      ENDIF                         '--would be set to LP.LoadPtrSeg only since
  1174.                                    '--LP.LoadPtrOff=0 as returned by LoadDac
  1175.      IF stat THEN   
  1176.         'file load error or deallocate error in stat
  1177.      ENDIF
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.                                                                               18
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.      SetAllDac           Func: 20       Pack: SetPack
  1196.  
  1197.      This routine sets the overall playback volume, interrupt rate, and RUCKUS
  1198.      priority in one call.
  1199.  
  1200.      The playback volume affects VOC or WAVE output for non-DMA mode, only. In
  1201.      other words, it's for controlling the volume on the PC speaker, LPT-DAC,
  1202.      Disney Sound Source, and AdLib only. To control the playback volume of the
  1203.      Sound Blaster, you must operate it under non-DMA mode. To control the
  1204.      playback of the Sound Blaster Pro, a separate set of RUCKUS routines are
  1205.      used. See the SetAllSBP routine for more.
  1206.  
  1207.      The default volume is set to 16. Minimum is 0, maximum is 127. For a linear
  1208.      approximation of this volume control, 16 is about half-volume, 8 about 1/4,
  1209.      64 about 3/4, and 127 full volume. A volume other than 16 may
  1210.      cause a slowdown in performance so 16 should be used as much as possible.
  1211.  
  1212.      Note: SETTING THE VOLUME TO 0 TURNS OFF THE SOUND BLASTER AND PRO'S
  1213.            SPEAKER (REQUIRED BEFORE RECORDING). ANY OTHER SETTING TURNS
  1214.            THE SPEAKER CONNECTION ON.
  1215.  
  1216.      The interrupt rate sets the playback rate of background play for non-DMA
  1217.      mode. For example, let's say you load a file that was recorded with a
  1218.      sample rate of 8000Hz (this information is stored with the VOC or WAVE).
  1219.      That is the value to which you set the interrupt rate. Easy enough. But
  1220.      let's say that it was recorded at 44,100Hz and in stereo. Normally, this
  1221.      data file couldn't be played except with high-end sound cards. What you can
  1222.      do is set the interrupt rate to 8000Hz and have RUCKUS-DAC perform on-the-
  1223.      fly downsampling so that you can play this file on any of the supported
  1224.      devices (in non-DMA mode).
  1225.  
  1226.      In addition to downsampling, RUCKUS-DAC can upsample with the PC Speaker
  1227.      and AdLib cards (the two that need it the most). Let's take that 8000Hz
  1228.      sample rate file again. Upsampling performs on-the-fly adjustments to the
  1229.      data so that it sounds as if the file sample rate were twice the original.
  1230.      This results in a much cleaner sound. There is a drawback: much more CPU
  1231.      time is needed at this high rate, and it should only be used on powerful
  1232.      CPUs. To use the upsampling capabilities of RUCKUS-DAC, set the interrupt
  1233.      rate to the original sample rate. There is also a special method used in
  1234.      the initialization of the device. See InitDac for more. You can experiment
  1235.      with the down- and upsampling of RUCKUS-DAC by using the MODAC.EXE program.
  1236.  
  1237.      When using non-DMA mode, you can select from three priority levels. The
  1238.      default priority=1. This level allows the system to run as normal, even
  1239.      though the computer's ticker has been sped up some thousand times. Priority
  1240.      level 2 hogs all background time for the RUCKUS-DAC playback. The
  1241.      computer's clock is not updated. Priority level 0 gives top priority to
  1242.      other computer events. This level may result in a warbly sound. Priority
  1243.      only affects non-DMA VOC/WAVE output. Use the default level (1).
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.                                                                               19
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.      The default interrupt rate is 10989. If you are on a slow machine, this may
  1262.      be too high for non-DMA operations. The following table shows the min, max,
  1263.      and nominal interrupt rate for the supported devices. In all cases, higher
  1264.      rates require more CPU power, except in DMA mode. Nominal values based on a
  1265.      386/25 CPU.
  1266.  
  1267.        Device   MinRate   MaxRate  Nominal  Comments
  1268.        ------   -------   -------  -------  ------------------------------------
  1269.        PCSKP0      5000     18000     8000  rates < 16000 may be noisy
  1270.        PCSPK1      5000      9000     8000  effective rate=rate*2
  1271.        LPTDAC      5000     23000    15000  not tested
  1272.        DISNEY      5000      7000     7000  max usable rate is 7000Hz
  1273.        ADLIB0      5000     12000     8000  AdLib very slow as digital device
  1274.        ADLIB1      5000      6000     6500  effective rate=rate*2
  1275.        SB          5000     23000    15000  DMA mode is 5-23000, record to 12kHz
  1276.        SB PRO      5000     23000    15000  DMA mode is 5-45500
  1277.  
  1278.      Sample Use:
  1279.  
  1280.      DIM SP AS SetPackTYPE
  1281.  
  1282.      SP.Func = SetAllDac
  1283.      SP.Volume = 16          'any other value slows down performance
  1284.      SP.IntRate = 8000      
  1285.      SP.Priority = 1
  1286.      stat = RUCKDAC(SP)
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.                                                                               20
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.      SetVolumeDac        Func: 21       Pack: SetPack
  1328.  
  1329.      SetVolumeDac does two things. First, it controls the non-DMA mode output
  1330.      volume. Second, it turns the SB's speaker on and off; the SB speaker must
  1331.      be off, and remain off, while recording. Under normal use, the SB speaker
  1332.      is turned on and off by RUCKUS automatically.
  1333.  
  1334.      Because of the extra calculations required when the volume is set to
  1335.      anything other than the default (16), it's recommended that the volume be
  1336.      changed only when necessary (especially on slow machines).
  1337.  
  1338.      This routine controls the output volume on all devices in non-DMA mode. In
  1339.      DMA-mode, the SB's volume is not controllable. The SB PRO, however, has a
  1340.      large set of mixer controls that can be controlled via RUCKUS-DAC. See
  1341.      SetAllSBP for more.
  1342.  
  1343.      Sample Use:
  1344.  
  1345.      DIM SP AS SetPackTYPE
  1346.  
  1347.      SP.Func = SetVolumeDac
  1348.      SP.Volume = 127           'set to max volume
  1349.      stat = RUCKDAC(SP)      
  1350.      IF stat THEN
  1351.         'you probably didn't set SP.Func correctly
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.                                                                               21
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.      SetIntRateDac       Func: 22       Pack: SetPack
  1394.  
  1395.      SetIntRateDac, with respect to the -DAC section of RUCKUS, controls the
  1396.      playback rate of non-DMA output.
  1397.  
  1398.      After loading a file, that file's sample rate is available in the DAC data
  1399.      section. You may choose to have the digital data file played back at that
  1400.      rate, or, you may choose to downsample the original rate. Downsampling is
  1401.      useful since it allows slower computers to play data files originally
  1402.      sampled at rates too high to be played back -- RUCKUS can play a 44.1kHz
  1403.      stereo VOC or WAVE file back through the PC speaker, or any of the other
  1404.      supported devices. Note that the actual downsampled rate is not always
  1405.      exactly what you specify, but a best-fit approximation.
  1406.  
  1407.      As an example, let's suppose you have a VOC file originally sampled at
  1408.      22050Hz, mono format. While this can easily be played on the SBs using DMA-
  1409.      mode playback, non-DMA mode requires a very powerful CPU to handle that
  1410.      high a rate. After loading using LoadDac, the 22050 sample rate, and its
  1411.      mono format, is determined by reading the DAC data section. To play back
  1412.      this file through PCSPKR0, say, at 11kHz, you'd set SP.IntRate=11025.
  1413.  
  1414.      With the PC speaker and the AdLib, there are two different output modes.
  1415.      The first either plays at the original rate, or is downsampled to a lower
  1416.      rate (as specified by you). The second mode upsamples. By upsampling,
  1417.      RUCKUS can output a much cleaner sound than playing at the original sample
  1418.      rate. However, this is useful only for samples that were originally at a
  1419.      low sample rate. You would not want to upsample a VOC file that was sampled
  1420.      at 22kHz, since that would demand too much CPU power, plus, very little
  1421.      benefit would be achieved. The best use of upsampling is on data that was
  1422.      originally sampled at, say, 8kHz or less. In order to properly upsample,
  1423.      you need to specify a SP.IntRate equal to the original sample rate (this
  1424.      can be found in the DAC data section immediately after a LoadDac).
  1425.  
  1426.      As mentioned, upsample mode is available on the speaker and AdLib devices
  1427.      only. To specify this mode, set the IP.IOport to the physical port when
  1428.      initializing the device (InitDac). In the PC speaker's case, IP.IOport=0x42
  1429.      (&H42) would activate up-sample mode. Using IP.IOport=0 would have the
  1430.      regular mode used. For the AdLib, specify IP.IOport=0x388 (&H388). As with
  1431.      the PC speaker, setting IP.IOport=0 uses the regular AdLib play mode.
  1432.  
  1433.      Sample Use:
  1434.  
  1435.      DIM SP AS SetPackTYPE
  1436.  
  1437.      SP.Func = SetIntRateDac
  1438.      SP.IntRate = 11025        'for rates > 32767 see RecordDac
  1439.      stat = RUCKDAC(SP)
  1440.      IF stat THEN 'error
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.                                                                               22
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.      SetPriorityDac      Func: 23       Pack: SetPack
  1460.  
  1461.      When operating in non-DMA mode playback of VOC or WAVE data, RUCKUS
  1462.      reprograms the system timer. Normally, this timer runs at the familiar 18.2
  1463.      times per second rate. When you play back at, say, a SP.IntRate=10000, this
  1464.      is the new rate that the system timer is set to operate at. So, instead of
  1465.      the timer interrupting the CPU (via IRQ0) 18.2/sec, it interrupts at
  1466.      10,000/sec. 
  1467.  
  1468.      The routine allows you to control the priority given to other events while
  1469.      the timer is operating at this accelerated pace. The default priority is 1.
  1470.      At the priority, the playback code is called at the desired rate, and,
  1471.      given a 10kHz rate, every 550th time the playback code is executed, the
  1472.      original timer-dependant code is executed. This allows the system clock,
  1473.      and any other system in the computer dependant on the clock, to be properly
  1474.      maintained. On each 550th call, RUCKUS first performs all tasks that needs
  1475.      to be done, then it calls the original system code. In most cases, if not
  1476.      all, this priority works best.
  1477.  
  1478.      Priority 0 is exactly like priority 1 except that control is released as
  1479.      soon as the RUCKUS code starts. The permits other tasks to interrupt
  1480.      RUCKUS. This may cause a warbly-type sound, but permits, say, high-speed
  1481.      communications code to operate in the background with missing a beat.
  1482.  
  1483.      Priority 2 causes RUCKUS to use (hog) all background processing time for
  1484.      itself. The system clock is not maintained. Use this priority only if the
  1485.      other two are causing problems (doubtful) or if you want to get the maximum
  1486.      sound performance out of RUCKUS and don't care if the system clock is
  1487.      maintained.
  1488.  
  1489.  
  1490.      Sample Use:
  1491.  
  1492.      DIM SP AS SetPackTYPE
  1493.  
  1494.      SP.Func = SetPriorityDac
  1495.      SP.Priority = 1       '1 is the default so no need to call unless changed
  1496.      stat = RUCKDAC(SP)
  1497.      IF stat THEN
  1498.         'check SP.Func for proper value
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.                                                                               23
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.      GetBufferDataDac    Func: 28       Pack: GetDataPack
  1526.  
  1527.      Used to get a specified number of bytes from the current digital data path.
  1528.  
  1529.      This routine is currently under development and should not be used.
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.                                                                               24
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.      GetBytePosDac       Func: 29       Pack: GetDataPack
  1592.  
  1593.      Used to determine where in the current digital data path processing is
  1594.      occurring.
  1595.  
  1596.      Sample Use:
  1597.  
  1598.      DIM GDP AS GetDataPackTYPE
  1599.  
  1600.      GDP.Func = GetBytePosDac
  1601.      stat = RUCKDAC(GDP)
  1602.      IF stat = 0 THEN
  1603.         PRINT "Curr pos relative start of data is "; HEX$(GDP.BytePos)
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.                                                                               25
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.      SetAllSBP           Func: 30       Pack: SetProPack
  1658.  
  1659.      This routine allows you to control the mixer facility of the Sound Blaster
  1660.      Pro including main volume, VOC volume, mic level, CD level, line level,
  1661.      output filter, input source selection, record filters, input source, and
  1662.      stereo/mono record mode.
  1663.  
  1664.      During initialization of the Sound Blaster Pro (InitDac), the main and VOC
  1665.      volumes are set to maximum (15) for both left and right channels, the three
  1666.      input levels are set to their minimums (1), all filters are set to off,
  1667.      mode is set to mono record, and input selection is set to mic.
  1668.  
  1669.      NOTE: PLAYBACK OF VOC AND WAVE STEREO DATA FILES IS AUTOMATIC. THE STEREO
  1670.            MODE SETTING IS FOR RECORDING ONLY. TO PLAY STEREO FILES IN MONO
  1671.            ON THE SB PRO, USE THE SOUND BLASTER (DEVICE 4) INSTEAD.
  1672.  
  1673.      The main volume (left and right, as are all mixer controls except mic)
  1674.      adjusts both the digital and synthesizer outputs of the PRO (the
  1675.      synthesizer, or FM section, is not used by RUCKUS-DAC, but is in RUCKUS-
  1676.      MIDI). In normal use the main volume channels would be set to 15, the
  1677.      maximum.
  1678.  
  1679.      The VOC volume adjusts the volume of the digital output channels. Anything
  1680.      played through the SB PRO's digital channels can be adjusted with this. As
  1681.      with the main volume, the VOC volume is normally set to 15, the maximum.
  1682.  
  1683.      The SB PRO provides for three inputs. Mic, CD, and Line. Each of these have
  1684.      separate level adjustments. The mic input level is the odd one out. Unlike
  1685.      the other two, the mic level does not adjust the mic input level, but
  1686.      rather the mic output level. Whenever you record via the mic input line at
  1687.      the back of the card, the input level is controlled by an AGC, automatic
  1688.      gain control. The AGC acts as a real-time level adjuster -- high signal
  1689.      levels (loud sounds) have the AGC automatically decrease the mic input
  1690.      sensitivity -- low signal levels (quiet sounds) have it automatically
  1691.      increase the mic input sensitivity. The actions of an AGC has its drawbacks
  1692.      in reduced dynamic range and perhaps a noticeable "breathing" of the sound
  1693.      on playback. Breathing is where the background noise increases as the level
  1694.      of the sound decreases. However, often the reduced dynamic range makes for
  1695.      a better final results, especially when using a mic/SB combination.
  1696.  
  1697.      The CD input level adjusts the level of the CD-ROM device. No testing has
  1698.      been done with this. It controls the input level from the proprietary CD-
  1699.      ROM drive that CLabs distributes for the SB PRO, or one which is compatible
  1700.      (and is hooked up to the SB PRO's CD connector). Any CD should be able to
  1701.      plug into the CD audio connector of the SB PRO (see the SB PRO docs) and so
  1702.      have its level controllable via RUCKUS-DAC.
  1703.  
  1704.      The Line input level adjusts the input sensitivity. Normally, when
  1705.      recording from this input, the Line level should be set to 15, the maximum.
  1706.      For preamps that have an unusually high line out level, reducing the PRO's
  1707.      line input level may produce a better recording.
  1708.  
  1709.      The output filter can be used to reduce the noise at the mid and high end
  1710.      of the digital data being played. Normally, this filter is not needed.
  1711.  
  1712.                                                                               26
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.      The recording filters are very useful and should be used whenever the
  1725.      recording sample rate is below 18kHz and the source being record has
  1726.      frequencies above 9kHz. There are two filters to choose from: one has a
  1727.      3.2kHz cutoff, the other 8.8kHz.
  1728.  
  1729.      Whenever you are recording from a source that will include frequencies
  1730.      higher than 3.2kHz, and you have the PRO recording at a sample rate under
  1731.      6.4kHz, you should select the 3.2kHz filter. This will attenuate
  1732.      frequencies higher than 3.2kHz and should help produce a cleaner recording.
  1733.      Along the same lines, if you are recording frequencies higher than 8.8kHz,
  1734.      and are recording using a sample rate less than 17.6kHz, you should use the
  1735.      8.8kHz filter. Note that filter use as described above is not a rule, just
  1736.      a guideline. You may find that using no filters is best.
  1737.  
  1738.      With the SB PRO you have 3 input sources to record from: the mic, a CD-ROM
  1739.      drive attached to the SB PRO (requires special cable), or a line-level
  1740.      input. The mic allows mono recording only. The CD-ROM facility controls
  1741.      only a CD-ROM drive hooked up to the SB PRO. The line input can be
  1742.      connected directly to a preamplifier's line out jacks.
  1743.  
  1744.      The SB PRO allows you to record in STEREO from the CD and LINE input
  1745.      sources; mic is always mono. When recording in stereo, the sample rate you
  1746.      record at must be set to twice the desired rate. For example, if you want
  1747.      to record from the LINE input at 22.05kHz, in stereo, set the recording
  1748.      rate to twice 22,050, or 44,100. The SB PRO can sample up to a 45,500Hz
  1749.      rate (which, if a stereo recording, is an effective rate of 22,750Hz). See
  1750.      RecordDac for more.
  1751.  
  1752.      Sample Use:
  1753.  
  1754.      DIM SPP AS SetProPackTYPE   'be careful not to type SBP
  1755.  
  1756.      SPP.Func = SetAllSBP
  1757.      leftCh = 15 : rightCh = 15            'set all output volumes to max
  1758.      SPP.Volume = (256 * leftCh) + rightCh 'could just use = &H0F0F
  1759.      SPP.VolVoc = (256 * leftCh) + rightCh
  1760.  
  1761.      leftCh = 1 : rightCh = 1              'set all input levels to minimum
  1762.      SPP.VolMic = leftCh                   'mic is mono, max is 7
  1763.      SPP.CD = (256 * leftCh) + rightCh
  1764.      SPP.LI = (256 * leftCh) + rightCh
  1765.  
  1766.      SPP.FilterOut = 0        '0=off filter, 1=on (output filter)
  1767.      SPP.FilterIn = 0         '0=off filter, 1=3.2kHz, 2=8.8kHz (record filter)
  1768.      SPP.SourceIn = 0         '0=mic, 1=CD, 2=line
  1769.      SPP.StereoIn = 0         'record mode: 0=mono, 1=stereo
  1770.  
  1771.      stat = RUCKDAC(SPP)
  1772.      IF stat = THEN 'error
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.                                                                               27
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.      SetVolMainSBP       Func: 31       Pack: SetProPack
  1790.  
  1791.      The main volume (left and right) adjusts both the digital and synthesizer
  1792.      outputs of the PRO; it is the overall volume setting. Each of these outputs
  1793.      also has its own volume control. In normal use, the main volume channels
  1794.      would be set to 15, the maximum.
  1795.  
  1796.      The range of volume is 1 to 15, in steps of 2 (1,3,5,7,9,11,13,15). To set
  1797.      the left channel main volume, multiply the volume desired by 256. To set
  1798.      the right channel, just add its value. For example, to set the main volume
  1799.      to maximum (15, or 0F hex), multiply 15*256 and add 15. In hex, this value
  1800.      is 0F0F (decimal 3855, but decimal is much too awkward). If you know
  1801.      beforehand that you want the main volume at maximum, you can forego the
  1802.      multiplication and simply use 0F0F, as in the example below.
  1803.  
  1804.      NOTE: Since you are the programmer and you have the documentation, do not
  1805.            depend on RUCKUS correcting out-of-value parameters. If you use 
  1806.            parameters that are not within specifications, the results are
  1807.            undefined.
  1808.  
  1809.      Sample Use:
  1810.  
  1811.      DIM SPP AS SetProPackTYPE
  1812.  
  1813.      SPP.Func = SetVolMainSBP
  1814.      SPP.Volume = &H0F0F
  1815.      stat = RUCKDAC(SPP)
  1816.      IF stat THEN 'error
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.                                                                               28
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.      SetVolVocSBP        Func: 32       Pack: SetProPack
  1856.  
  1857.      The VOC volume (left and right) adjusts the digital output volume of the
  1858.      PRO. The range of volume is 1 to 15, in steps of 2 (1,3,5,7,9,11,13,15). To
  1859.      set the left channel VOC volume, multiply the volume desired by 256. To set
  1860.      the right channel, just add its value. For example, to set the VOC volume
  1861.      to maximum (15, or 0F hex), multiply 15*256 and add 15. In hex, this value
  1862.      is 0F0F (decimal 3855, but decimal is much too awkward). If you know
  1863.      beforehand that you want the VOC volume at maximum, you can forego the
  1864.      multiplication and simply use 0F0F, as in the example below.
  1865.  
  1866.      Sample Use:
  1867.  
  1868.      DIM SPP AS SetProPackTYPE
  1869.  
  1870.      SPP.Func = SetVolMainSBP
  1871.      SPP.VolVoc = &H0F0F
  1872.      stat = RUCKDAC(SPP)
  1873.      IF stat THEN 'error
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.                                                                               29
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.      SetLevelMicSBP      Func: 33       Pack: SetProPack
  1922.  
  1923.      This routine does not actually adjust the mic input level, but rather the
  1924.      mic output level. Whenever you record via the mic input line at the back of
  1925.      the card, the input level is controlled by an AGC, automatic gain control.
  1926.      The AGC acts as a real-time level adjuster -- high signal levels (loud
  1927.      sounds) have the AGC automatically decrease the mic input sensitivity --
  1928.      low signal levels (quiet sounds) have it automatically increase the mic
  1929.      input sensitivity. The actions of an AGC has its drawbacks in reduced
  1930.      dynamic range and perhaps a noticeable "breathing" of the sound on
  1931.      playback. Breathing is where the background noise increases as the level of
  1932.      the sound decreases. However, often the reduced dynamic range makes for a
  1933.      better final results, especially when using a mic/SB combination.
  1934.  
  1935.      By setting the mic input level, you can use the computer as a public
  1936.      address system. To do this, select mic as the input source, set the mic
  1937.      input level to maximum, and turn on the SB speaker. To avoid feedback, keep
  1938.      the mic away from the loudspeakers.
  1939.  
  1940.      The input level range is 1 to 7, in steps of 2 (1,3,5,7). This setting has
  1941.      no effect on recording level (see above).
  1942.  
  1943.      Sample Use:
  1944.  
  1945.      DIM SPP AS SetProPackTYPE
  1946.  
  1947.      SPP.Func = SetVolMicSBP
  1948.      SPP.VolVoc = &H0007
  1949.      stat = RUCKDAC(SPP)
  1950.      IF stat THEN 'error
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.                                                                               30
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.      SetLevelCDSBP       Func: 34       Pack: SetProPack
  1988.  
  1989.      The CD input level (left and right) adjusts the input level of the attached
  1990.      CD-ROM drive. This has not been tested. For its use, see SetLevelLineSBP.
  1991.  
  1992.  
  1993.  
  1994.  
  1995.  
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.                                                                               31
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.      SetLevelLineSBP     Func: 35       Pack: SetProPack
  2054.  
  2055.      The line level (left and right) adjusts the analog input level of the PRO.
  2056.      The range of volume is 1 to 15, in steps of 2 (1,3,5,7,9,11,13,15). To set
  2057.      the left channel line level, multiply the volume desired by 256. To set the
  2058.      right channel, just add its value. For example, to set the line level to
  2059.      maximum sensitivity (15, or 0F hex), multiply 15*256 and add 15. In hex,
  2060.      this value is 0F0F (decimal 3855, but decimal is much too awkward). If you
  2061.      know beforehand that you want the line level at maximum, you can forego the
  2062.      multiplication and simply use 0F0F, as in the example below.
  2063.  
  2064.      Sample Use:
  2065.  
  2066.      DIM SPP AS SetProPackTYPE
  2067.  
  2068.      SPP.Func = SetVolMainSBP
  2069.      SPP.VolLI = &H0F0F
  2070.      stat = RUCKDAC(SPP)
  2071.      IF stat THEN 'error
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.                                                                               32
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.      SetFilterOutSBP     Func: 36       Pack: SetProPack
  2120.  
  2121.      The output filter of the PRO can be used to reduce the noise at the mid and
  2122.      high end of the digital data being played. Normally, this filter is not
  2123.      needed. Recordings made at a very low sample rate, say, under 6kHz, may
  2124.      sound better with this output filter on.
  2125.  
  2126.      The digital output filter, and also the analog recording filter, is set off
  2127.      by default. 
  2128.  
  2129.      Sample Use:
  2130.  
  2131.      DIM SPP AS SetProPackTYPE
  2132.  
  2133.      SPP.Func = SetFilterOutSBP
  2134.      SPP.FilterOut = 1          'enable output filter
  2135.      stat = RUCKDAC(SPP)
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.                                                                               33
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.      SetFilterInSBP      Func: 37       Pack: SetProPack
  2186.  
  2187.      The recording filters are very useful and should be used whenever the
  2188.      recording sample rate is below 18kHz and the source being record has
  2189.      frequencies above 9kHz. There are two filters to choose from: one has a
  2190.      3.2kHz cutoff, the other 8.8kHz.
  2191.  
  2192.      Whenever you are recording from a source that will include frequencies
  2193.      higher than 3.2kHz, and you have the PRO recording at a sample rate under
  2194.      6.4kHz, you should select the 3.2kHz filter. This will attenuate
  2195.      frequencies higher than 3.2kHz and should help produce a cleaner recording.
  2196.      Along the same lines, if you are recording frequencies higher than 8.8kHz,
  2197.      and are recording using a sample rate less than 17.6kHz, you should use the
  2198.      8.8kHz filter. Note that filter use as described above is not a rule, just
  2199.      a guideline. You may find that using no filters is best.
  2200.  
  2201.      The input filter is off by default.
  2202.  
  2203.      Sample Use:
  2204.  
  2205.      DIM SPP AS SetProPackTYPE
  2206.  
  2207.      SPP.Func = SetFilterInSBP
  2208.      SPP.FilterIn = 1           '0=no filter, 1=3.2kHz cutoff, 2=8.8kHz cutoff
  2209.      stat = RUCKDAC(SPP)
  2210.      IF stat THEN 'error
  2211.  
  2212.  
  2213.  
  2214.  
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.                                                                               34
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.      SetSourceSBP        Func: 38       Pack: SetProPack
  2252.  
  2253.      With the SB PRO you have three input sources to record from: the mic, a CD-
  2254.      ROM drive attached to the SB PRO (requires special cable), or a line-level
  2255.      input. The mic allows mono recording only. The CD-ROM facility controls
  2256.      only a CD-ROM drive hooked up to the SB PRO. The line input can be
  2257.      connected directly to a preamplifier's line out jacks.
  2258.  
  2259.      Recording with the mic requires only that it be selected. The mic input
  2260.      level does not control the recording level, but rather the PA output. See
  2261.      SetAllSBP for more.
  2262.  
  2263.      Recording from the connected CD-ROM drive has not been tested. If you can
  2264.      control the CD, you can record from it using RUCKUS.
  2265.  
  2266.      Recording from the line-level input is simple. Just hook your tape-out
  2267.      jacks from your preamplifier to the cable supplied with the SB PRO. This
  2268.      cable, a 1/8-inch mini stereo to 2 RCA phono jacks is the same one that
  2269.      comes with the original Sound Blaster. You'll probably need more cable
  2270.      unless you have your preamp nearby. 
  2271.  
  2272.      When recording from either the CD or line, you must set the source's input
  2273.      level. Normally, setting it to maximum (15) is best. If you have
  2274.      particularly high line output levels, you may need to set this lower. As
  2275.      with all mixer settings, settings are 1 to 15 in steps of 2. The mic is 1
  2276.      to 7, by 2.
  2277.  
  2278.      Sample Use:
  2279.  
  2280.      DIM SPP AS SetProPackTYPE
  2281.  
  2282.      SPP.Func = SetSourceSBP
  2283.      SPP.SourceIn = 2          'set input source to line input
  2284.      stat = RUCKDAC(SPP)
  2285.      IF stat THEN 'error
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.                                                                               35
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.      SetStereoSBP        Func: 39       Pack: SetProPack
  2318.  
  2319.      The SB PRO allows you to record in STEREO from the CD and LINE input
  2320.      sources; mic is always mono. When recording in stereo, the sample rate you
  2321.      record at must be set to twice the desired rate. For example, if you want
  2322.      to record from the LINE input at 22.05kHz, in stereo, set the recording
  2323.      rate to twice 22,050, or 44,100. The SB PRO can sample up to a 45,500Hz
  2324.      rate (which, if a stereo recording, is an effective rate of 22,750Hz). See
  2325.      RecordDac for more.
  2326.  
  2327.      You must set the mode to stereo or mono before starting the actual record.
  2328.  
  2329.      Sample Use:
  2330.  
  2331.      DIM SPP AS SetProPackTYPE
  2332.  
  2333.      SPP.Func = SetStereoSBP
  2334.      SPP.StereoIn = 1          'set to stereo record
  2335.      stat = RUCKDAC(SPP)
  2336.      IF stat THEN 'error
  2337.  
  2338.  
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.                                                                               36
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.      SetSpeakerSB        Func: 40       Pack: SetPack
  2384.  
  2385.      The routine activates or deactivates the Sound Blasters' output. When
  2386.      recording it must be off. When playing back, it must be on. When starting a
  2387.      recording, RUCKUS automatically turns the speaker off; when playing back it
  2388.      turns the speaker on. For those occasions when you want to control the
  2389.      speaker connection, use this routine.
  2390.  
  2391.      Note that the generic SetVolumeDac also controls the SB's speaker
  2392.      connection. If the speaker is currently on and you set the volume to 0, the
  2393.      SB speaker is turned off. And, of the speaker is currently off, and you set
  2394.      the volume to a non-zero value, the speaker is turned on. This routine lets
  2395.      you control the connection without changing the generic volume setting.
  2396.  
  2397.      Sample Use:
  2398.  
  2399.      DIM SP AS SetPackTYPE     
  2400.  
  2401.      SP.Func = SetSpeakerSB
  2402.      SP.Volume = 0             'use the volume member of SP to control speaker
  2403.      stat = RUCKDAC(SP)        'to turn the speaker on, set SP.Volume = 1
  2404.      IF stat THEN 'error       'THIS DOES NOT ALTER THE VOLUME
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.                                                                               37
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.      GetMixerRegSBP      Func: 48       Pack: GetDataPack
  2450.  
  2451.      Get a SB PRO mixer port-value.
  2452.  
  2453.      This routine is under development and should not be used.
  2454.  
  2455.  
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.  
  2474.  
  2475.  
  2476.  
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.                                                                               38
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.      GetDacSB            Func: 49       Pack: GetDataPack
  2516.  
  2517.      This routine gets a byte from the Sound Blasters data channel. This routine
  2518.      should not be called while the Sound Blaster is playing or record. It can
  2519.      be used for level tests.
  2520.  
  2521.      Before using this routine on the PRO, first select the input device (mic,
  2522.      CD, or line) and then perform a 64-byte record from that device. This is
  2523.      because the input device is not selected until you actually record from it.
  2524.  
  2525.      Unlike the other RUCKDAC routines, the return value is not the error code,
  2526.      but rather the data byte itself. To check for an error, use GDP.stat (as
  2527.      you can in all RUCKUS functions).
  2528.  
  2529.      Sample Use:
  2530.  
  2531.      DIM GDP AS GetDataPackTYPE
  2532.  
  2533.      GDP.Func = GetDacSB
  2534.      data = RUCKDAC(GDP)
  2535.      IF GDP.stat THEN 'error
  2536.  
  2537.  
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.                                                                               39
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.      ExitMod             Func: 50       Pack: XitPack
  2582.  
  2583.      When using RUCKUS, certain aspects of the computer are controlled by the
  2584.      RUCKUS code. To have RUCKUS return full control back to the computer and
  2585.      operating system, ExitMod must be called. To ensure that this happens, even
  2586.      after an abnormal termination (such as an untrapped divide by zero), RUCKUS
  2587.      also provides a routine that ensures that ExitMod is always called before
  2588.      your application ends and returns to the operating system. See AtExitMod
  2589.      for more.
  2590.  
  2591.      Once you have loaded a mod file via LoadMod, or performed any mod function,
  2592.      you must call ExitMod before you end you program and return to DOS. Calling
  2593.      ExitMod releases any memory allocations made, and also performs other
  2594.      system cleanup.
  2595.  
  2596.      Sample Use:
  2597.  
  2598.      DIM XP AS ExitPackTYPE
  2599.  
  2600.      XP.Func = ExitMod
  2601.      stat = RUCKDAC(XP)
  2602.      IF stat THEN 'error
  2603.  
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.                                                                               40
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.      AtExitMod           Func: 51       Pack: XitPack
  2648.  
  2649.      To ensure that all machine control is returned to the operating system and
  2650.      that all RUCKUS-made memory allocations are released, before your
  2651.      application program ends, AtExitMod should be used (if you have used the
  2652.      mod extensions to RUCKUS-DAC). This routine takes advantage of most
  2653.      compiler's _atexit enregistration routine. This _atexit compiler run-time
  2654.      library routine allows for up to 32 different calls to be made just prior
  2655.      to it (the compiler's run-time code) returning to the operating system
  2656.      (program termination). Most of the time, you can make all the necessary
  2657.      shutdowns that your program requires in your app's code. However, abnormal
  2658.      terminations--terminations that can cause a bypass of your own shutdown
  2659.      code, may mean that when the operating systems regains control, certain
  2660.      machine operations are not in a stable state. The AtExitMod routine ensures
  2661.      that ExitMod is called no matter what (in most all cases, except where the
  2662.      program locks up, in which case the session needs to be reset anyway). 
  2663.  
  2664.      Graphically, your program executes like this:
  2665.  
  2666.         DOS C>program.exe
  2667.           |
  2668.         Compiler startup code (performs basic setup)
  2669.           |
  2670.           +----->+
  2671.                  | Your program starts, ends
  2672.           +<-----+
  2673.           |   
  2674.          rest of startup code, _atexit registered routines
  2675.           |
  2676.          DOS C>_
  2677.  
  2678.      Caution: In order for the _atexit registered routines to be called by your
  2679.      compilers run-time, you must not allow you program to exit via non-standard
  2680.      ways. Calling INT21/4C is on example (you should never do this from
  2681.      compiled code, anyway).
  2682.  
  2683.      The startup code is basically a program that sets up your program to run,
  2684.      calls your program, regains control when your program ends, then performs
  2685.      the necessary shutdown actions required, including calling all routines
  2686.      registered with _atexit.
  2687.  
  2688.      Sample Use:
  2689.  
  2690.      DIM XP AS ExitPack
  2691.  
  2692.      XP.Func = AtExitMod
  2693.      stat = RUCKDAC(XP)
  2694.      IF stat THEN PRINT "_atexit is full (more than 32 calls made to _atexit)"
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.                                                                               41
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.      LoadMod             Func: 52       Pack: LoadPack
  2714.  
  2715.      It is required that RUCKUS load mod files into memory. RUCKUS makes the
  2716.      necessary memory allocations and loads the data into conventional memory,
  2717.      with UMB blocks used if available and controlled by DOS (via DOS=,UMB in
  2718.      CONFIG.SYS). Only one mod file may be in memory at any one time. To unload
  2719.      the mod file you must execute an ExitMod call.
  2720.  
  2721.      LoadMod can be instructed to start loading at any particular byte in a
  2722.      file. This would be useful, for example, if you have a single file made up
  2723.      of several mod files, appended to form one large data file.
  2724.  
  2725.      Sample Use:
  2726.  
  2727.      DIM LP AS LoadPackTYPE
  2728.  
  2729.      nix& = SETMEM(700000)
  2730.      mem& = SETMEM(0)
  2731.      nix& = SETMEM(mem& - 2100) 'release all but 2K to the OS
  2732.                                 'or as much as needed to store file
  2733.      LP.Func = LoadMod
  2734.      LP.FilenamePtrOff = SADD(filename$)
  2735.      LP.FilenamePtrSeg = VARSEG(filename$)
  2736.       'BASIC7 or VB/DOS use:
  2737.       'LP.FilenamePtrOff = SADD(filename$)
  2738.       'LP.FilenamePtrSeg = SSEG(filename$)
  2739.      LP.StartPos = 0&   'start load at first byte of file
  2740.      LP.LoadSize = 0&   'have RUCKUS load all of it
  2741.      LP.XMMflag = 0     'this must be set to zero
  2742.      stat = RUCKDAC(LP)
  2743.      IF stat = 0 THEN
  2744.         'LP.LoadPtr is not used for Mod loads
  2745.         nix& = SETMEM(700000) 
  2746.      ELSE
  2747.         nix& = SETMEM(700000)  '700,000 tells BASIC to reclaim unused memory
  2748.         'file load error in stat
  2749.      ENDIF
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.                                                                               42
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.      PlayMod             Func: 53       Pack: PlayBackPack
  2780.  
  2781.      Once the mod file has been loaded, you can play it to any of the RUCKUS-
  2782.      supported devices. There are 4 modes that can be used for playback; non-DMA
  2783.      foreground, non-DMA background, DMA foreground, and DMA background. The DMA
  2784.      modes require the Sound Blasters. Also, for STEREO mod playback, DMA mode
  2785.      is required (SB Pro only).
  2786.  
  2787.      Playing in the background allows your computer program to regain control
  2788.      immediately after play has begun. If you choose foreground play, control
  2789.      does not return to your program until the end of the data has been played,
  2790.      or, until CTRL-ALT is pressed. In all cases, mod file playback is best done
  2791.      on a fast computer, though excellent results can be gotten from 286-class
  2792.      machines. For slow machines, DMA foreground allows for best sound, since
  2793.      you can set the mod process rate higher than you can if you choose a
  2794.      background mode.  
  2795.  
  2796.      Before play, you should set up other parameters by calling the other Set
  2797.      mod routines (SetIntRateMod, SetStereoMod, and SetFastMod).
  2798.  
  2799.      NOTE: SOME MACHINES ARE NOT ABLE TO HANDLE BACKGROUND DMA MODE AT HIGH 
  2800.            RATES, EVEN ON 486-CLASS MACHINES. HOWEVER, BOTH MY 486/33 AND
  2801.            MY 286/16 WORK WELL IN THIS MODE. THE 486/33 CAN PROCESS MOD DATA
  2802.            AT RATES UP TO THE PRO'S MAX, 45,500Hz. THE 286/16 CAN PROCESS UP 
  2803.            TO 16kHz IN THIS MODE AND 22kHz IN DMA FOREGROUND. A 286/6 HAS 
  2804.            BEEN TESTED TO 8kHz (DMA FOREGROUND) AND PERFORMS WELL. A 12MHz
  2805.            DID 16kHz. ON SLOWER MACHINES, USING A LARGER DMA BUFFER SIZE
  2806.            AND A HIGHER DMAX: VALUE ALLOWS FOR HIGHER RATES TO BE ACHIEVED.
  2807.            IT IS POSSIBLE TO LOCK UP A MACHINE IF TOO HIGH A RATE IS ATTEMPTED.
  2808.  
  2809.      DIM PBP AS PlaybackPackTYPE
  2810.  
  2811.      PBP.Func = PlayMod
  2812.      PBP.Mode = 3        'mode 0=foreground, 1=background, 2=DMA FG, 3=DMA BG
  2813.      PBP.XMMhandle = 0   'this must be set to 0
  2814.  
  2815.      'PBP.LoadPtr is not used by PlayMod
  2816.  
  2817.      PBP.BufferSize = 4096 'buffer size is bytes per buffer (2 buffers used)
  2818.                            'minimum size is 2048, maximum is 64K-16
  2819.                            'buffers allocated only if DMA play (mode=2 or 3)
  2820.      stat = RUCKDAC(PBP)
  2821.      IF stat = 0 THEN
  2822.         'if background mode then the mod data is playing now, 
  2823.         'but if foreground mode, the play has ended by the time we get here
  2824.      ELSE
  2825.         'play error (could be not enough memory for PBP.BufferSize)
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.                                                                               43
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.      EndMod              Func: 54       Pack: XitPack
  2846.  
  2847.      EndMod is used to end (stop) play on command. Once PlayMod has started, it
  2848.      continues to play in the background until either the end of the mod data
  2849.      has been reached, or you call this routine.
  2850.  
  2851.      Sample Use:
  2852.  
  2853.      DIM XP AS ExitPackTYPE
  2854.  
  2855.      'LoadMod and PlayMod have already been called
  2856.      'see those routines for more information
  2857.  
  2858.      XP.Func = EndMod      'if play is active this call
  2859.      stat = RUCKDAC(XP)    'ends it
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.                                                                               44
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.      PauseMod            Func: 55       Pack: PausePack
  2912.  
  2913.      PauseMod allows you to temporarily pause and then restart a playback.
  2914.  
  2915.      Sample Use:
  2916.  
  2917.      DIM PP AS PausePackTYPE
  2918.  
  2919.      PP.Func = PauseMod
  2920.      PP.Pause = 1        'non-zero pauses, zero restarts
  2921.      stat = RUCKDAC(PP)
  2922.  
  2923.      PRINT "Press a key to continue playback"
  2924.      a$ = INPUT$(1)
  2925.  
  2926.      PP.Pause = 0
  2927.      stat = RUCKDAC(PP)  'continue playback
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.                                                                               45
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.      SetIntRateMod       Func: 56       Pack: SetModPack
  2978.  
  2979.      SetIntRateMod, with respect to the mod extensions of RUCKUS, controls the
  2980.      mod data processing rate, which in turn, is the playback rate (the opposite
  2981.      of sample rate).
  2982.  
  2983.      A process rate of 22kHz should be considered a practical maximum. Higher
  2984.      process rates are possible (up to 45.5kHz with the PRO) but the improvement
  2985.      in sound quality over 22kHz is negligible (to me). If the machine is
  2986.      capable, a rate of at least 16kHz should be used. At this rate, sound is
  2987.      reasonably good sounding. Rates below 16kHz will most likely incur a high-
  2988.      pitched whistling noise that can be very annoying. Using the output filter
  2989.      of the SB PRO helps. The whistle is totally absent from the output of the
  2990.      Disney Sound Source (which internally plays at 7kHz regardless of the input
  2991.      stream rate). For PC speaker output, rates above 18kHz are not recommended.
  2992.      Best performance for the PC speaker is at 16kHz. The AdLib, being a very
  2993.      slow device when made to play digital data, has an effective top-end of
  2994.      about 13kHz. 
  2995.  
  2996.      When using the SB PRO in stereo mode, the mod process rate must not exceed
  2997.      45.5kHz/2, or 22.75kHz. This is a limitation of the Sound Blaster. In mono,
  2998.      you can run up to 45.5kHz, if you have the muscle to do so (typically
  2999.      requires a 486, and a DMAX: setting of at least 4). Buffer sizes above 4K
  3000.      matter most on slower machines.
  3001.  
  3002.      Adjusting the mod processing while playing is permitted, though it's
  3003.      recommended to do so only when not.
  3004.  
  3005.      Sample Use:
  3006.  
  3007.      DIM SMP AS SetModPackTYPE
  3008.  
  3009.      SMP.Func = SetIntRateMod
  3010.      SMP.IntRate = 22000      'for rates >32767 see SetRecordDac 
  3011.      stat = RUCKDAC(SMP)
  3012.      IF stat THEN 'error
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.                                                                               46
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.      SetSpeedMod         Func: 57       Pack: SetModPack
  3044.  
  3045.      Temporarily increases or decreases the playback speed of the mod file
  3046.      playing. The basic speed of a mod, with regard to this routine, is 6.
  3047.      However, at any particular point in the mod file this can change.
  3048.  
  3049.      The speed range is 1 to 15, with 1 resulting in fast play, and 15 resulting
  3050.      in a very slow play.
  3051.  
  3052.      Sample Use:
  3053.  
  3054.      DIM SMP AS SetModPackTYPE
  3055.  
  3056.      SMP.Func = SetSpeedMod
  3057.      SMP.Speed = 4           'increase play by 33% over norm
  3058.      stat = RUCKDAC(SMP)
  3059.      IF stat THEN 'error
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.                                                                               47
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.      SetVolumeMod        Func: 58       Pack: SetModPack
  3110.  
  3111.      SetVolumeMod controls each of the four mod digital output channels.
  3112.      Normally they would all be set to maximum (255). In order to adjust channel
  3113.      volume, FastMod mode must be off.
  3114.  
  3115.      Sample Use:
  3116.  
  3117.      DIM SMP AS SetModPackTYPE
  3118.  
  3119.      SMP.Func = SetVolumeMod
  3120.      SMP.VolCh1 = 255
  3121.      SMP.VolCh2 = 255
  3122.      SMP.VolCh3 = 255
  3123.      SMP.VolCh4 = 255
  3124.      stat = RUCKDAC(SMP)      
  3125.      IF stat THEN 'error
  3126.  
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.  
  3134.  
  3135.  
  3136.  
  3137.  
  3138.  
  3139.  
  3140.  
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.                                                                               48
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.      SetPositionMod      Func: 59       Pack: SetModPack
  3176.  
  3177.      Each mod file is composed of several tracks, known as patterns. Each
  3178.      pattern contains 64*4 notes (64 notes per channel). A mod file can contain
  3179.      up to 63 separate patterns, and can play up to 128 patterns in total
  3180.      (though any pattern can be made to repeat). SetPositionMod lets you move to
  3181.      the start of any pattern to be played (up to the number of patterns to
  3182.      play). The first pattern is pattern number 0. The last possible patter
  3183.      number is 127.
  3184.  
  3185.      Sample Use:
  3186.  
  3187.      DIM SMP AS SetModPackTYPE
  3188.  
  3189.      SMP.Func = SetPositionMod
  3190.      SMP.Position = 0           'restart play from the beginning
  3191.      stat = RUCKDAC(SMP)      
  3192.      IF stat THEN 'error
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.                                                                               49
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.      SetStereoMod        Func: 60       Pack: SetModPack
  3242.  
  3243.      Mod data files contain four channels of information. In mono playback mode,
  3244.      all four of these are combined to form a single digital output stream. In
  3245.      stereo mode (SB PRO only), you can select from three different combine
  3246.      modes. You can increase this to nine stereo combinations by setting the
  3247.      high bit of SMP.Stereo. If set, the left/right channels are reversed.
  3248.  
  3249.      Sample Use:
  3250.  
  3251.      DIM SMP AS SetModPackTYPE
  3252.  
  3253.      SMP.Func = SetPositionMod
  3254.      SMP.Stereo = 1            '0=mono
  3255.      stat = RUCKDAC(SMP)       '1=LEFT:ch1+ch3  RIGHT:ch2+ch4
  3256.      IF stat THEN 'error       '2=LEFT:ch1+ch4  RIGHT:ch2+ch3
  3257.                                '3=LEFT:ch1+ch2  RIGHT:ch3+ch4
  3258.                                '&H8000 + mode then LEFT <-> RIGHT, e.g.,
  3259.                                '&H8001=LEFT:ch2+ch4  RIGHT:ch1+ch3
  3260.  
  3261.  
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.                                                                               50
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.      SetFastMod          Func: 61       Pack: SetModPack
  3308.  
  3309.      Mod files require lost of CPU power and lots of CPU attention. The most
  3310.      often executed code performs 4 BPTR IMUL instructions every tick of a
  3311.      process clock (10,000 times/sec if that is the process rate selected).
  3312.      Multiply on the 8088 is a very time consuming operation. If an 8088-based
  3313.      computer is to play mod files, these multiplies must be sped up. SetFastMod
  3314.      performs this task by implementing an alternate method. Note that with
  3315.      FastMod mode enable, some mod files may sound odd.
  3316.  
  3317.      The SliceAdj instructs the DMA buffer fill code to perform more than one
  3318.      mix per interrupt. By increasing this number you reduce the interrupt-
  3319.      latency time wasted (since more mod data is processed per interrupt) but
  3320.      you also decrease the amount of time given to other tasks (tasks other than
  3321.      mod playback). Fast CPUs have no problem keeping the DMA buffers full, so
  3322.      even a large SliceAdj will have little of any impact on these machines.
  3323.      However, on slow machines where the DMA buffers are constantly needing to
  3324.      be filled (where neither DMA buffer is ever filled) a SliceAdj above 1 may
  3325.      be desirable. Typically, though, the default of 1 works fine.
  3326.  
  3327.      Sample Use:
  3328.  
  3329.      DIM SMP AS SetModPackTYPE
  3330.  
  3331.      SMP.Func = SetFastMod
  3332.      SMP.FastMode = -1         '0=normal, 1=fast mode enabled, -1 to skip
  3333.      SMP.SliceAdj = 32         'DMA buffer fill count (1-4096, default=1)
  3334.      stat = RUCKDAC(SMP)    
  3335.      IF stat THEN 'error    
  3336.  
  3337.  
  3338.  
  3339.  
  3340.  
  3341.  
  3342.  
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.  
  3362.                                                                               51
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.      Appendix A. Tips and Tricks.
  3374.  
  3375.      See the RUCKUS-MIDI documenation.
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  
  3390.  
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.                                                                               52
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.      Appendix B. Pack Structure.
  3440.  
  3441.      DECLARE FUNCTION RUCKDAC% (SEG packinfo AS ANY)
  3442.  
  3443.      CONST SysInfoDac = 0, InitDac = 1, ExitDac = 2, AtExitDac = 3
  3444.      CONST LoadDac = 4, PlayDac = 5, RecordDac = 6
  3445.      CONST StoreDac = 7, EndDac = 8, PauseDac = 9
  3446.      CONST DeallocDac = 10
  3447.  
  3448.      CONST SetAllDac = 20, SetVolumeDac = 21, SetIntRateDac = 22
  3449.      CONST SetPriorityDac = 23
  3450.      CONST GetBufferDataDac = 28, GetBytePosDac = 29
  3451.  
  3452.      CONST SetAllSBP = 30, SetVolMainSBP = 31, SetVolVocSBP = 32
  3453.      CONST SetLevelMicSBP = 33, SetLevelCDSBP = 34, SetLevelLineSBP = 35
  3454.      CONST SetFilterOutSBP = 36, SetFilterInSBP = 37
  3455.      CONST SetSourceSBP = 38, SetStereoSBP = 39
  3456.  
  3457.      CONST SetSpeakerSB = 40
  3458.      CONST GetMixerRegSBP = 48, GetDacSB = 49
  3459.  
  3460.      CONST ExitMod = 50, AtExitMod = 51
  3461.      CONST LoadMod = 52, PlayMod = 53
  3462.      CONST EndMod = 54, PauseMod = 55
  3463.      CONST SetIntRateMod = 56, SetSpeedMod = 57
  3464.      CONST SetVolumeMod = 58, SetPositionMod = 59
  3465.      CONST SetStereoMod = 60, SetFastMod = 61
  3466.  
  3467.      TYPE DeallocPackTYPE      'DP
  3468.       Func       AS INTEGER
  3469.       stat       AS INTEGER
  3470.       HandSeg    AS INTEGER    'RUCKUS allocates either XMM handle or DOS para
  3471.       TypeFlag   AS INTEGER    '0=DOS para, 1=XMS handle (not used for Mods)
  3472.      END TYPE '8
  3473.  
  3474.      TYPE GetDataPackTYPE      'GDP
  3475.       Func       AS INTEGER
  3476.       stat       AS INTEGER
  3477.       BytePos    AS LONG       'ret:current byte relative base ptr (27)
  3478.       BufferPtrOff AS INTEGER  'far pointer to buffer to fill with data,offset
  3479.       BufferPtrSeg AS INTEGER  'segment
  3480.       StartPos   AS LONG       'start get at this offset relative BufferPtr
  3481.       BufferCnt  AS INTEGER    'bytes to fill (2-65520)
  3482.       MixerReg   AS INTEGER    'SBPro mixer register to get
  3483.      END TYPE '20
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.                                                                               53
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.      TYPE InitPackTYPE         'IP
  3506.       Func       AS INTEGER
  3507.       stat       AS INTEGER
  3508.       DeviceID   AS INTEGER    '0=SPKR,1=LPTDAC,2=DSS,4=SB,5=SBPro
  3509.       IOport     AS INTEGER
  3510.       IRQline    AS INTEGER
  3511.       DMAch      AS INTEGER
  3512.       Flags      AS INTEGER    '(see Appendix D. RUCKUS-DAC Data Area)
  3513.       InfoPtrOff AS INTEGER    'ret:far ptr to dac info
  3514.       InfoPtrSeg AS INTEGER
  3515.       DacExitPtrOff AS INTEGER 'ret:far ptr to dac's ExitXB routine
  3516.       DacExitPtrSeg AS INTEGER
  3517.       ModExitPtrOff AS INTEGER 'ret:far ptr to mod's ExitXB routine
  3518.       ModExitPtrSeg AS INTEGER
  3519.      END TYPE '24
  3520.  
  3521.      TYPE LoadPackTYPE          'LP
  3522.       Func       AS INTEGER
  3523.       stat       AS INTEGER
  3524.       FilenamePtrOff AS INTEGER 'far ptr to filenameZ to load
  3525.       FilenamePtrSeg AS INTEGER
  3526.       StartPos   AS LONG        'offset into file to start load at
  3527.       LoadSize   AS LONG        'number of bytes to load (or 0 for autosize)
  3528.       XMMflag    AS INTEGER     'if <> 0 use XMS for load
  3529.       XMMhandle  AS INTEGER     'ret:XMS handle, or
  3530.       LoadPtrOff AS INTEGER     'ret:DOS seg:offset (offset always 0)
  3531.       LoadPtrSeg AS INTEGER     'LoadPtr not used for Mod loads
  3532.      END TYPE '20
  3533.  
  3534.      TYPE PlaybackPackTYPE      'PBP
  3535.       Func       AS INTEGER
  3536.       stat       AS INTEGER
  3537.       Mode       AS INTEGER     '(0=interrupt FG,1=BG,2=DMA,3=DMA+BG for mod)
  3538.       XMMhandle  AS INTEGER     'if <> 0 this XMM handle used regardless
  3539.       LoadPtrOff AS INTEGER     'seg:off to start of data to play
  3540.       LoadPtrSeg AS INTEGER
  3541.       BufferSize AS INTEGER     'size of DMA buffer for mod playback
  3542.      END TYPE '14
  3543.  
  3544.      TYPE PausePackTYPE         'PP
  3545.       Func       AS INTEGER
  3546.       stat       AS INTEGER
  3547.       Pause      AS INTEGER     '0=unpause else pause
  3548.      END TYPE '6
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.                                                                               54
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.      TYPE RecordPackTYPE        'RP
  3572.       Func         AS INTEGER
  3573.       stat         AS INTEGER
  3574.       SampleRate   AS INTEGER
  3575.       XMMhandle    AS INTEGER   '-1 auto XMS (ret in dx) else use this handle
  3576.       RecordPtrOff AS INTEGER   'seg:off of buffer to store (0 for auto-store)
  3577.       RecordPtrSeg AS INTEGER   'ret: RecordPtr->buffer used (or in XMMhandle)
  3578.       RecordBytes  AS LONG      'bytes to record
  3579.       StereoFlag   AS INTEGER   'stereo flag
  3580.      END TYPE '18
  3581.  
  3582.      TYPE SaveDataPackTYPE      'SDP
  3583.       Func       AS INTEGER
  3584.       stat       AS INTEGER
  3585.       FilenamePtrOff AS INTEGER 'far ptr to filenameZ to save
  3586.       FilenamePtrSeg AS INTEGER
  3587.       DataPtrOff AS INTEGER     'pointer to start of data to save, offset
  3588.       DataPtrSeg AS INTEGER     'segment (or 0 if XMS)
  3589.       FileType   AS INTEGER     '1=VOC,2=WAV
  3590.       XMMhandle  AS INTEGER     'XMS handle of data to save (0 if DOS data)
  3591.      END TYPE '16
  3592.  
  3593.      TYPE SetPackTYPE           'SP
  3594.       Func       AS INTEGER
  3595.       stat       AS INTEGER     '(if volume=0 SB speaker off'ed else on'ed)
  3596.       Volume     AS INTEGER     'volume (left ch=MSB,right=LSB) (0-127,0-127)
  3597.       IntRate    AS INTEGER     'playback interrupt rate (5000-23000)
  3598.       Priority   AS INTEGER     'priority level (0-2, default=1)
  3599.      END TYPE '18
  3600.  
  3601.      TYPE SetModPackTYPE        'SMP                    'stereo modes
  3602.       Func       AS INTEGER                             'A=ch1+ch3 & ch2+ch4
  3603.       stat       AS INTEGER                             'B=?
  3604.       VolCh1     AS INTEGER     'channel volume (0-255) 'C=?
  3605.       VolCh2     AS INTEGER     'channel volumes adjustments made only
  3606.       VolCh3     AS INTEGER     ' if FastMode=0
  3607.       VolCh4     AS INTEGER
  3608.       Stereo     AS INTEGER     'playback mode (0=mono,stereo 1=A,2=B,3=C)
  3609.       FastMode   AS INTEGER     'fast playback (0=normal,1 fast,no ch volumes)
  3610.       IntRate    AS INTEGER     'playback interrupt rate (5000-45500)
  3611.       Position   AS INTEGER     'pattern list position (0-patterns to play)
  3612.       Speed      AS INTEGER     'overall playback speed (1-15,default=6,15=slow)
  3613.       SliceAdj   AS INTEGER     'DMA buffer fill count (1-4096, default=1)
  3614.      END TYPE '24
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.                                                                               55
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.      TYPE SetProPackTYPE        'SPP
  3638.       Func       AS INTEGER
  3639.       stat       AS INTEGER
  3640.       Volume     AS INTEGER     'volume (low=right;0-15, high byte=left;0-15)
  3641.       VolVoc     AS INTEGER     '
  3642.       VolMic     AS INTEGER     '(mono only, 0-7) input level
  3643.       VolCD      AS INTEGER     'input level (0-15,0-15)
  3644.       VolLI      AS INTEGER     'input level (0-15,0-15)
  3645.       FilterOut  AS INTEGER     '0=filter off, 1=filter on
  3646.       FilterIn   AS INTEGER     '0=filter off, 1=3.2kHz, 2=8.8kHz
  3647.       SourceIn   AS INTEGER     '0=mic,1=CD,2=line
  3648.       StereoIn   AS INTEGER     '0=mono,1=stereo record
  3649.      END TYPE '22
  3650.  
  3651.      TYPE XitPackTYPE           'XP
  3652.       Func       AS INTEGER
  3653.       stat       AS INTEGER
  3654.      END TYPE '4
  3655.  
  3656.  
  3657.  
  3658.  
  3659.  
  3660.  
  3661.  
  3662.  
  3663.  
  3664.  
  3665.  
  3666.  
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.                                                                               56
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.      TYPE SysInfoPackTYPE       'SIP
  3704.       Func       AS INTEGER     
  3705.       stat       AS INTEGER
  3706.       CPU        AS INTEGER     'CPU class (88,286,386,486)
  3707.       CPUmode    AS INTEGER     '0=real mode,1=PM,2=PM w/paging
  3708.       MHz        AS INTEGER     'approx speed (5,20,33)
  3709.       Device0    AS INTEGER     '=1 speaker available
  3710.       D0port     AS INTEGER     '42h
  3711.       D0IRQ      AS INTEGER     'n/a
  3712.       D0DMA      AS INTEGER     'n/a
  3713.       D0flags    AS INTEGER     'bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY
  3714.       Device1    AS INTEGER     '=1 LPT-DAC available on LPT1
  3715.       D1port     AS INTEGER     'port of _first_ LPT found in BIOS data area
  3716.       D1IRQ      AS INTEGER     'n/a
  3717.       D1DMA      AS INTEGER     'n/a
  3718.       D1flags    AS INTEGER     'bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY
  3719.       Device2    AS INTEGER     '=1 Disney Sound Source available
  3720.       D2port     AS INTEGER     'port of DSS
  3721.       D2IRQ      AS INTEGER     'n/a
  3722.       D2DMA      AS INTEGER     'n/a
  3723.       D2flags    AS INTEGER     'bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY
  3724.       Device3    AS INTEGER     '=1 AdLib available
  3725.       D3port     AS INTEGER     '388h
  3726.       D3IRQ      AS INTEGER     'n/a
  3727.       D3DMA      AS INTEGER     'n/a
  3728.       D3flags    AS INTEGER     'bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY
  3729.       Device4    AS INTEGER     '=1 SB available
  3730.       D4port     AS INTEGER     'port of SB
  3731.       D4IRQ      AS INTEGER     'IRQ
  3732.       D4DMA      AS INTEGER     'DMA
  3733.       D4flags    AS INTEGER     'bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY
  3734.       Device5    AS INTEGER     '=1 SBPro available
  3735.       D5port     AS INTEGER     'port of SBPro
  3736.       D5IRQ      AS INTEGER     'IRQ
  3737.       D5DMA      AS INTEGER     'DMA
  3738.       D5flags    AS INTEGER     'bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY
  3739.      END TYPE '70
  3740.  
  3741.      TYPE SysDevTYPE            'SD (used by BASIC 7.1 compiler)
  3742.       device     AS INTEGER     '=1 device available
  3743.       port       AS INTEGER
  3744.       IRQ        AS INTEGER
  3745.       DMA        AS INTEGER
  3746.       Flags      AS INTEGER     'bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY
  3747.      END TYPE '10
  3748.  
  3749.      TYPE SysInfoPackTYPE7      'SIP   BASIC 7.1: SIP.SD(0).device = ...
  3750.       Func       AS INTEGER     '******* UNCOMMENT-OUT SD(0 TO 5) BELOW
  3751.       stat       AS INTEGER
  3752.       CPU        AS INTEGER     'CPU class (88,286,386,486)
  3753.       CPUmode    AS INTEGER     '0=real mode,1=PM,2=PM w/paging
  3754.       MHz        AS INTEGER     'approx speed (5,20,33)
  3755.       ''SD(0 TO 5) AS SysDevTYPE  'QB45 won't accept arrays in TYPEs
  3756.      END TYPE '70
  3757.  
  3758.                                                                               57
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.      Appendix C. Compiler, Linker, QLB, and Call Use.
  3770.  
  3771.      Compile and Link.
  3772.  
  3773.      To create a stand-alone EXE file, compile your BASIC source as required. No
  3774.      special compiler switches are required. When your compiler is finished and
  3775.      has reported no errors during the compile, use the LINK program supplied
  3776.      with your compiler to resolve any external references in your BASIC program
  3777.      code that are dependent on the RUCKUS library code.
  3778.  
  3779.      For example, if you have a single-module BASIC source file called
  3780.      SOUND.BAS, compile it:
  3781.  
  3782.       C>bc SOUND /o;
  3783.  
  3784.      If successful, use the LINK program to build the final EXE:
  3785.  
  3786.       C>link SOUND,SOUND.EXE,nul,RUCKDAC.LIB RUCKMIDI.LIB;
  3787.  
  3788.      If successful, link creates SOUND.EXE ready to be run at the DOS prompt.
  3789.      The BASIC runtime is also supported by RUCKUS. Just compile as you normally
  3790.      would (without the /o, of course).
  3791.  
  3792.      RUCKUS is composed of many separate assembly language modules in two
  3793.      separate LIBs, one for digital data and the other for MIDI data.
  3794.  
  3795.      If you need to use more libraries with your programs, no problem, LINK can
  3796.      handle as many as you have. When LINK prompts you for a library file, just
  3797.      enter RUCKDAC.LIB and RUCKMIDI.LIB followed by any other library you need.
  3798.      For example:
  3799.  
  3800.       C>link
  3801.  
  3802.       Microsoft (R) Segmented Executable Linker  Version 5.31.009 Jul 13 1992
  3803.       Copyright (C) Microsoft Corp 1984-1992.  All rights reserved.
  3804.  
  3805.       Object Modules [.OBJ]: SOUND+STUB
  3806.       Run File [.EXE]: SOUND.EXE
  3807.       List File [NUL.MAP]: nul
  3808.       Libraries [.LIB]: RUCKDAC RUCKMIDI MOUSE;
  3809.  
  3810.      Consult your linker programs documentation for more.
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.                                                                               58
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.      Creating a QLB.
  3836.  
  3837.      If you use the QuickBASIC environment to program in, you need to build a
  3838.      .QLB so that you can call the RUCKUS routines. While QuickBASIC can load
  3839.      only a
  3840.      single QLB ( C>qb /L quicklib.qlb ), you can combine many LIB and OBJ
  3841.      modules to create the QLB. For example, to make a QLB of the RUCKDAC.LIB,
  3842.      RUCKMIDI.LIB and MOUSE.LIB libraries:
  3843.  
  3844.       C>link /QU RUCKDAC.LIB+RUCKMIDI.LIB+MOUSE.LIB, IDE.QLB, nul, BQLB45.LIB;
  3845.  
  3846.      Note the extension .LIB on the library modules. This is REQUIRED since LINK
  3847.      assumes .OBJ by default. The quick library, BQLB45.LIB, is required for the
  3848.      Libraries: prompt. The exact name depends on the compiler version. Consult
  3849.      your compiler documentation for more.
  3850.  
  3851.      BASIC PDS note: BASIC PDS requires that all BASIC modules included into a
  3852.      QLB be compiled using the /Fs compiler switch. This instructs the compiler
  3853.      to
  3854.      generate code compatible with "far strings". Since RUCKUS is written
  3855.      entirely in assembly language, this is not an issue. However, if you start
  3856.      QBX.EXE with /L and get an INVALID FORMAT error, one of the modules in the
  3857.      .QLB file most likely was a BASIC module that was not compiled with the /Fs
  3858.      switch.
  3859.  
  3860.  
  3861.      Calling RUCKDAC() and RUCKMIDI().
  3862.  
  3863.      RUCKUS is called through a single entry point. Depending on function
  3864.      (digital or MIDI) you use either RUCKDAC() or RUCKMIDI(). The only argument
  3865.      passed to is a segmented far pointer to the control pack. The first two
  3866.      entries in this pack are the function to be performed and the function
  3867.      return status. RUCKUS is a FUNCTION call returning an INTEGER status value
  3868.      (with a few exceptions, see the documentation).
  3869.  
  3870.      Each function (or routine) uses a prescribed pack format. For example, some
  3871.      routines need only know the function to perform. For example, to end a
  3872.      digital play you could do the following:
  3873.  
  3874.       DIM XP AS XitPackTYPE          'could also DIM SHARED
  3875.  
  3876.       XP.Func = EndDac               'EndDac is defined in RUCKDAC.BI
  3877.       stat = RUCKDAC(XP)             'do the actual call to RUCKUS-DAC
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.                                                                               59
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.      Appendix D. RUCKUS-DAC Data Area.
  3902.  
  3903.      The offset value below is relative InfoPtrOff as returned by InitDac. For
  3904.      example, to access dac@end, the following code can be used:
  3905.  
  3906.      DEF SEG = IP.InfoPtrSeg
  3907.      DacIsOver = PEEK(IP.InfoPtrOff + 10)
  3908.      DEF SEG
  3909.  
  3910.      For accessing word (dw) and double-word (dd) values, see Appendix A in the
  3911.      RUCKUS-MIDI document. Most dac@ variables are PUBLIC symbols and may be
  3912.      accessed directly by compilers that allow external references to variables.
  3913.      QuickBASIC does not so the DEF SEG method needs to be used. Where possible,
  3914.      access all dac@ data through a common function so that future changes can
  3915.      be easily made.
  3916.  
  3917.      Name           Type    Offset Comments ------------------------------
  3918.      dac@deviceID    dw      +0    device ID
  3919.      dac@IOport      dw       2    port of device
  3920.      dac@IRQ         dw       4    IRQ of device
  3921.      dac@DMA         dw       6    DMA of device
  3922.      dac@Flags       dw       8    bit0=1 use DOS UMB memory
  3923.                                    bit1-4 reserved
  3924.                                    bit5=1 force XMS2 to be used
  3925.                                    bit6=1 force device speaker on until exit
  3926.                                    bit7=1 force passed parms to be used
  3927.                                           Following values are ret bits
  3928.                                    bit8=1 paging mechanism in force, no UMBs
  3929.                                    bit9-15 reserved
  3930.      dac@end         dw       10   =1 end of play
  3931.      dac@pause       dw       12   =1 pause play
  3932.      dac@endmod      dw       14   =1 end of mod play                       
  3933.      dac@memDOS      dw       16   DOS memory available (in K)
  3934.      dac@memXMM      dw       18   XMS memory available (in K)
  3935.  
  3936.      dac@type        dw       20   digital type (1=VOC w/header,2=WAV)
  3937.      dac@memUsed     dw       22   memory used for last file load (in K)
  3938.      dac@sampleRate  dw       24   sample rate currently playing
  3939.      dac@stereo      dw       26   stereo
  3940.      dac@vocLen      dd       28   length of voc block (only current block)
  3941.      dac@vocPtrPtr   dd       32   pointer to pointer->current data
  3942.  
  3943.      dac@recordLen   dd       36   length of recorded data
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.  
  3955.  
  3956.                                                                               60
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.      dac@sbpMixerPtr dd       40   pointer to SBP mixer data
  3969.                                   ;-4=farptr to SB data start(sbc@IRQnum)
  3970.                                   ;+0=volMasterR,+2=L
  3971.                                   ;+4=volVocR,+6=L
  3972.                                   ;+8=volMic
  3973.                                   ;+10=volCDR,+12=CDL
  3974.                                   ;+14=volLIR,+16=LIL
  3975.                                   ;+18=filterInOff,+20=filterOutOff
  3976.                                   ;+22=input source selected
  3977.                                   ;+24=input cutoff freq selected
  3978.                                   ;+26=1=stereo data output
  3979.                                   ;+27=1=high sample rate (>23kHz)
  3980.                                   ;+28=SB speaker on=1/off=0
  3981.                                   ;+30=DSPver (1xx, 2xx, 3xx)
  3982.                                   ;+32=sbc@DSPtype 1=SB2 or below, 3=SBPro
  3983.      dac@modDataPtr  dd       44   pointer to mod data
  3984.  
  3985.  
  3986.      Additional Mod Data Section relative dac@modDataPtr above:
  3987.  
  3988.      Name           Type   Offset  Comments ------------------------------
  3989.      mod@type        dw      +0    mod type (15 or 31 samples)
  3990.      mod@samples     dw       2    number of instrument samples in mod
  3991.      mod@headerSeg   dw       4    header segment (aka sample info)
  3992.      mod@patternSeg  dw       6    pats' segment (1 to pats2play 1K patterns)
  3993.      mod@sampleSeg   dw31     8 (+62) ;list of sample segments
  3994.      mod@stereo      dw      70    =1 then play in stereo (only SBPro)
  3995.      mod@fastMode    dw      72    =1 then channel volume adjusts disabled
  3996.  
  3997.      mod@mt_patListPos  dw   74    byte pos within mod@patterList (0-127)
  3998.      mod@mt_notePatPos  dw   76    note pos within pattern 1K area (0-1008)
  3999.                                    pattern#=patternList(patListPos)
  4000.                                    note is at offset (pattern#*1024)+notePatPos
  4001.                                    -- in segment mod@patternSeg
  4002.      mod@hiPattern   dw      78    highest pattern number to play/+1!/ (0-63)
  4003.      mod@pats2play   dw      80    pats to play (direct DOS file load here)
  4004.      mod@patternList db128   82  (+128) ;pattern positions (to here)
  4005.      mod@MKoverflow  db6     210 (+6) ;overflow for 31-instr patpos read
  4006.  
  4007.      mod@memUsed     dw      216   DOS RAM needed by mod file (in para)
  4008.      mod@VS          dw      218   times VS handler entered (50Hz rate)
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.                                                                               61
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.      Appendix Z. Ordering Information, License Agreement and Product Support.
  4034.  
  4035.      To order you must you the order form included with the distribution files.
  4036.      Its filename is !ORDER.FRM. Orders made without this form may be delayed.
  4037.  
  4038.      There are two RUCKUS packages available. The PERSONAL DEVELOPER version is
  4039.      for the hobby-programmer while the PROFESSIONAL version is for the
  4040.      professional programmer.
  4041.  
  4042.      The PERSONAL DEVELOPER version is for persons that are not creating
  4043.      programs for distribution to others. With the PERSONAL DEVELOPER license
  4044.      you may not distribute any programs you create with RUCKUS. In addition, a
  4045.      sign-on banner is issued once, displaying the RUCKUS copyright and license
  4046.      restriction.
  4047.  
  4048.      The PROFESSIONAL version has no distribution restrictions on end-user
  4049.      programs you create with RUCKUS. The PROFESSIONAL license provides you with
  4050.      the right to create all the end-user programs royalty-free. You also have
  4051.      direct access to the latest version of RUCKUS free-of-charge by way of my
  4052.      support BBS and the RUCKUS Developer's Conference there. No sign-on banner
  4053.      is issued.
  4054.  
  4055.  
  4056.  
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.                                                                               62
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.      License Agreement
  4100.  
  4101.      Before using this software you must agree to the following:
  4102.  
  4103.      1. You are not allowed to operate more than one (1) copy of this software
  4104.      package at one time per license. This means that if you have 10 programmers 
  4105.      that COULD possibly use the RUCKUS library at the same time, you must also  
  4106.      have ten (10) RUCKUS licenses. 
  4107.  
  4108.      2. You are not allowed to distribute non-executable code containing RUCKUS 
  4109.      code. This means that you are not allowed to redistribute RUCKUS code as    
  4110.      another .LIB, for example. Also, if RUCKUS code is to be contained in a    
  4111.      Dynamic Link Library (DLL) then it must be part of a stand-alone product. 
  4112.      This means that you cannot provide a .DLL containing RUCKUS code if that    
  4113.      .DLL is to be used as a programming library for other programmers. If you   
  4114.      wish to distribute non-executable code containing RUCKUS code you must    
  4115.      obtain written permission from the author.
  4116.  
  4117.      3. This license grants you the right to use the RUCKUS library code on a   
  4118.      royalty-free basis, except when the license is the PERSONAL DEVELOPER, in
  4119.      which case you may not distribute any program in which RUCKUS has been
  4120.      used.
  4121.  
  4122.      4. RUCKUS is owned by the author, Cornel Huth, and is protected by United  
  4123.      States copyright laws and international treaty provisions. You are not    
  4124.      allowed to make copies of this software except for archival purposes.
  4125.  
  4126.      5. You may not rent or lease RUCKUS. You may not transfer this license
  4127.      without the written permission of the author. If this software is an update
  4128.      or upgrade, you may not sell or give away previous versions.
  4129.  
  4130.      6. You may not reverse engineer, decompile, or disassemble this software.
  4131.  
  4132.      7. There are no expressed or implied warranties with this software.
  4133.  
  4134.      8. All liabilities in the use of this software rest with the user.
  4135.  
  4136.      9. U.S. Government Restricted Rights. This software is provided with    
  4137.      restricted rights. Use, duplication, or disclosure by the Government is    
  4138.      subject to restrictions as set forth in subparagraph (c)(1)(ii) of the    
  4139.      Rights in Technical Data and Computer Software clause at 52.227-7013.    
  4140.      Manufacturer is Cornel Huth/6402 Ingram Rd/San Antonio, TX 78238.
  4141.  
  4142.      This agreement is governed by the laws of the state of Texas.
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.                                                                               63
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.      Product Support
  4166.  
  4167.      Support is available 7 days/week from 17:00 to 09:00 Central Time at my
  4168.      BBS, the Fortieth Floor, at 1.210.684.8065.
  4169.  
  4170.      PROFESSIONAL version licensees have free access to all future RUCKUS
  4171.      updates and upgrades via the RUCKUS Developer's Conference on the Fortieth
  4172.      Floor BBS (1.210.684.8065). PERSONAL DEVELOPER licensees have restricted
  4173.      access to in-version maintenance updates at no charge.
  4174.  
  4175.      End of the RUCKUS-DAC DOCUMENT. See also the RUCKUS-MIDI DOCUMENT.
  4176.  
  4177.  
  4178.  
  4179.  
  4180.  
  4181.  
  4182.  
  4183.  
  4184.  
  4185.  
  4186.  
  4187.  
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.                                                                               64
  4221.  
  4222.  
  4223.  
  4224.  
  4225.