home *** CD-ROM | disk | FTP | other *** search
/ Sound, Music & MIDI Collection 2 / SMMVOL2.bin / PROG / BWSB120A.ZIP / BWSB-REF.DOC next >
Encoding:
Text File  |  1980-01-04  |  56.2 KB  |  1,487 lines
  1.  
  2.                     Bells, Whistles, and Sound Boards
  3.                          REFERENCE DOCUMENTATION
  4.  
  5.                 v1.20 for ASM, C/C++, TP, QB, PDS, and PB
  6.                         PLEASE DISTRIBUTE FREELY
  7.  
  8.                  Copyright (c) 1993-95, Edward Schlunder
  9.                            All Rights Reserved
  10.  
  11.    This project was started on 07-14-93 and now completed on 05-25-95
  12.             (two years have been put into the making of BWSB)
  13.  
  14.   Disclaimer
  15.   ---------------------------------------------------------------------
  16.      In  no  event  shall  the  author  be  liable  for  any damages
  17.      whatsoever  (including, without limitation, damages for loss of
  18.      business profits, business interruption, loss of business data,
  19.      or  any  other  pecuniary loss) arising  out  of  the use of or
  20.      inability  to  use  this product, even  if  the author has been
  21.      advised    of   the   possibility   of   such   damages.   Some
  22.      states jurisdictions  do not allow  the exclusion or limitation
  23.      of liability for consequential or incidental damages. We do not
  24.      sell to people from such perverse places.
  25.  
  26.   License Agreement
  27.   ---------------------------------------------------------------------
  28.      This  software is protected by United States copyright laws and
  29.      international  treaty provisions. Therefore  you must treat the
  30.      software  like  any other  copyrighted material (books, musical
  31.      recordings,  etc).
  32.  
  33.      You  have  a  royalty-free right  to  reproduce  and distribute
  34.      executable  files  created  using  BWSB,  including the runtime
  35.      modules  (*.MSE)  required for operation.  You  may not produce
  36.      applications  which  require  payment from  end users with this
  37.      license. Register BWSB to get rights to produce profitable apps
  38.  
  39.      With your publically released programs, you must:
  40.  
  41.      (a) only distribute the runtime modules and executable files in
  42.      conjunction  with and part of your software product (ie, do not
  43.      include  OBJ  or source files);  (b)  include a valid copyright
  44.      notice  on your software product;  (c) agree to indemnify, hold
  45.      harmless,  and  defend  the authors  of  this software from and
  46.      against any claims or lawsuits, including attorneys' fees, that
  47.      arise  or result from the use  or distribution of your software
  48.      product.
  49.  
  50.      The  included source code may be edited anyway you wish, except
  51.      that  original copyright notices must remain unaltered. You are
  52.      prohibited   from   reverse  engineering,   decompiling,     or
  53.      disassembling any part of this software.
  54.  
  55.      This  product  is provided as is  and  the author disclaims all
  56.      other  warranties,  either expressed  or implied, including but
  57.      not  limited  to  implied  warranties  of  merchantability  and
  58.      fitness for a particular purpose.
  59.  
  60.      This agreement is governed by the laws of the state of Arizona.
  61.  
  62.   Quick Reference
  63.   ---------------------------------------------------------------------
  64.      NOTE: * denotes not usable yet
  65.  
  66.     *AllocSample       Allocate a sample slot (for sound effects)
  67.      AmigaHertz        Set Amiga Clock speed (for period calculations)
  68.      ChannelPan        Get or set a channel's pan position
  69.      ChannelPos        Get or set current play position on channel
  70.      ChannelVol        Get or set a channel's volume setting
  71.      ChannelVU         Get or set a channel's VU value
  72.      DeviceName        Returns the name of the current sound device
  73.      EmsExist          Determine whether EMS services exist or not
  74.      FreeMSE           Remove MSE from memory
  75.     *FreeSample        Remove a sample slot (free it for other uses)
  76.      GetChannelTable   Get information on a channel
  77.      GetMainScope      Get the currently played sample for a scope
  78.      GetSampleTable    Get information on a sample
  79.      LoadGDM           Load a GDM module from disk
  80.      LoadMSE           Load MSE file from disk
  81.      MixForground      Mix sound in the foreground
  82.      MixStatus         Get mix request flag
  83.      MusicBPM          Get or set the BPM speed
  84.      MusicLoop         Get times music has looped; set loop enable flag
  85.      MusicStatus       Get music processing enable status
  86.      MusicOrder        Get or set the music playing order number
  87.      MusicPattern      Get or set the music playing pattern number
  88.      MusicRow          Get the music playing row
  89.      MusicTempo        Get or set the music Tempo
  90.      MusicVolume       Get or set the global music volume
  91.      PlaySample        Play sound effect already loaded into MSE memory
  92.      SetAutoMix        Select foreground mixing or background mixing
  93.      StartMusic        Enable music processing
  94.      StartOutput       Turn on sound mixing
  95.      StopMusic         Disable music processing
  96.      StopOutput        Turn off sound mixing
  97.      UnloadModule      Free the loaded module from memory
  98.  
  99.   AllocSample
  100.   ---------------------------------------------------------------------
  101.      Purpose:  Load a sample slot with sample data
  102.  
  103.      Syntax:
  104.        [C/C++] extern int cdecl AllocSample(unsigned char SamNum,
  105.                SamHeader *SamHead);
  106.       [QB/PDS] DECLARE FUNCTION AllocSample% (SamNum%, SamHeadSeg%,
  107.                SamHeadOff%)
  108.           [TP] Function AllocSample(SamNum : Byte; Var SamHead) : Word;
  109.          [ASM] extrn AllocSample:far
  110.  
  111.      Remarks:  You need to load the sample data into memory prior to
  112.                calling this routine. It needs to be loaded into base
  113.                memory using DOS's allocation routine (ie, segment
  114.                aligned).
  115.  
  116.                This routine currently only uses base memory for sample
  117.                data. It does not work with GUS at this time.
  118.  
  119.      Calling:
  120.          cl    SamNum      - Sample slot number to put the sample into.
  121.                (0..255)      Note: Try to use high order sample slots
  122.                              because the music will always use sample
  123.                              slots starting from 0.
  124.          dx:si SamHeader   - This structure must be filled with all
  125.                              proper information for the sample before
  126.                              calling this routine. Those which do not
  127.                              apply to sound effect samples should be set
  128.                              to zero.
  129.  
  130.      Returns:
  131.          ax    AllocSample - Error code:
  132.                              0 - No Error, do not dealloc sample from
  133.                                  DOS
  134.                              1 - No Error, should dealloc sample from
  135.                                  DOS
  136.                              2 - Sample slot already used
  137.                              3 - Insufficient memory for sample
  138.  
  139.      See Also: FreeSample
  140.  
  141.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  142.  
  143.      Example:  none
  144.  
  145.   AmigaHertz
  146.   ---------------------------------------------------------------------
  147.      Purpose:  Set the Amiga clock speed for music period calculations
  148.  
  149.      Syntax:
  150.        [C/C++] extern void cdecl AmigaHertz(long NewSpeed);
  151.       [QB/PDS] DECLARE SUB AmigaHertz (NewSpeed&)
  152.           [TP] Procedure AmigaHertz(NewSpeed : Longint);
  153.          [ASM] extrn AmigaHertz:far
  154.  
  155.      Remarks:  none
  156.  
  157.      Calling:
  158.          eax   NewSpeed    - New Amiga clock speed for period
  159.                              calculations. Some common values are:
  160.                              3579545 (Amiga NTSC Machines, Default)
  161.                              3546895 (Amiga PAL Machines)
  162.                              3579264 (Scream Tracker)
  163.  
  164.      Returns:  none
  165.  
  166.      See Also: none
  167.  
  168.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  169.  
  170.      Example:  none
  171.  
  172.   ChannelPan
  173.   ---------------------------------------------------------------------
  174.      Purpose:  Get or set the specified channel's panning position
  175.  
  176.      Syntax:
  177.        [C/C++] extern int cdecl ChannelPan(unsigned char Channel,
  178.                unsigned char NewPos);
  179.       [QB/PDS] DECLARE FUNCTION ChannelPan% (Channel%, NewPos%)
  180.           [TP] Function ChannelPan(Channel, NewPos : Byte) : Byte;
  181.          [ASM] extrn ChannelPan:far
  182.  
  183.      Remarks:  Setting all the channels to one side or the other may
  184.                result in cracks and clicks in the output (except on the
  185.                GUS). Try to keep the number of locations more or less
  186.                balanced on left and right sides.
  187.  
  188.                Note also that positions between Left, Middle, and Right
  189.                require additional CPU time (except on the GUS).
  190.  
  191.      Calling:
  192.          bl    Channel     - Channel number to get or set pan on.
  193.                (1..32)
  194.          al    NewPos      - New pan position. 0 is full left, 15 is
  195.                (FFh, 0..15)  full right, 8 is middle. Positions in
  196.                              between are varying degrees of Left and
  197.                              Right together.
  198.  
  199.                              FFh does not affect pan position.
  200.  
  201.      Returns:
  202.          al    ChannelPan  - Current pan position in use.
  203.                (0..15)
  204.  
  205.      See Also: ChannelVol
  206.  
  207.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  208.  
  209.      Example:  none
  210.  
  211.   ChannelPos
  212.   ---------------------------------------------------------------------
  213.      Purpose:  Get or set current location in playback on a channel
  214.  
  215.      Syntax:
  216.        [C/C++] extern unsigned int cdecl ChannelPan(unsigned char
  217.                Channel, unsigned int NewPos);
  218.       [QB/PDS] DECLARE FUNCTION ChannelPos& (Channel%, NewPos&)
  219.           [TP] Function ChannelPos(Channel : Byte, NewPos : Word)
  220.                : Word;
  221.          [ASM] extrn ChannelPos:far
  222.  
  223.      Remarks:  This is most useful when playing digital samples larger
  224.                than 64K and for synchronizing speech with a graphical
  225.                character on screen.
  226.  
  227.      Calling:
  228.          bl    Channel     - Channel number to get or set position on.
  229.                (1..32)
  230.          ax    NewPos      - New play position. FFFFh does no changing.
  231.                (FFFFh, 0..65534)
  232.  
  233.      Returns:
  234.          ax    ChannelPos  - Current play position in sample.
  235.                (0..65535)
  236.  
  237.      See Also: PlaySample
  238.  
  239.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  240.  
  241.      Example:  none
  242.  
  243.   ChannelVol
  244.   ---------------------------------------------------------------------
  245.      Purpose:  Get or set the channel's volume setting
  246.  
  247.      Syntax:
  248.        [C/C++] extern int cdecl ChannelVol(unsigned char Channel,
  249.                unsigned char NewVol);
  250.       [QB/PDS] DECLARE FUNCTION ChannelVol% (Channel%, NewVol%)
  251.           [TP] Function ChannelVol(Channel, NewVol : Byte) : Word;
  252.          [ASM] extrn ChannelVol:far
  253.  
  254.      Remarks:  none
  255.  
  256.      Calling:
  257.          bl    Channel     - Channel number to get or set volume on.
  258.                (1..32)
  259.          al    NewVol      - New volume to play at. FFh does not change
  260.                (FFh, 0..64)  current volume.
  261.  
  262.      Returns:
  263.          ax    ChannelVol  - Current volume setting in use.
  264.                (0..64)
  265.  
  266.      See Also: ChannelVU, ChannelPan
  267.  
  268.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  269.  
  270.      Example:  none
  271.  
  272.   ChannelVU
  273.   ---------------------------------------------------------------------
  274.      Purpose:  Get or set the channel's VU bar setting
  275.  
  276.      Syntax:
  277.        [C/C++] extern int cdecl ChannelVU(unsigned char Channel,
  278.                unsigned char NewVU);
  279.       [QB/PDS] DECLARE FUNCTION ChannelVU% (Channel%, NewVU%)
  280.           [TP] Function ChannelVU(Channel, NewVU : Byte) : Word;
  281.          [ASM] extrn ChannelVU:far
  282.  
  283.      Remarks:  none
  284.  
  285.      Calling:
  286.          bl    Channel     - Channel number to get or set volume on.
  287.                (1..32)
  288.          al    NewVU       - New VU level. FFh does not change
  289.                (FFh, 0..32)  current VU level.
  290.  
  291.      Returns:
  292.          ax    ChannelVU   - Current VU level in use.
  293.                (0..32)
  294.  
  295.      See Also: ChannelVol, ChannelPan
  296.  
  297.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  298.  
  299.      Example:  none
  300.  
  301.   DeviceName
  302.   ---------------------------------------------------------------------
  303.      Purpose:  Return the name of the current sound device
  304.  
  305.      Syntax:
  306.        [C/C++] extern char *DeviceName(void);
  307.       [QB/PDS] DECLARE FUNCTION DeviceName$ ()
  308.           [TP] Function DeviceName : String;
  309.          [ASM] extrn DeviceName:far
  310.  
  311.      Remarks:  none
  312.  
  313.      Calling:  none
  314.  
  315.      Returns:
  316.          dx:ax DeviceName  - Name of the current sound device in use.
  317.                (<=20 chars)
  318.  
  319.      See Also: LoadMSE
  320.  
  321.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM, LOAD_PDS.BAS,
  322.                LOAD_QB.BAS
  323.  
  324.      Example:  PLAYC.C, MMP.BAS, GDMPLAY.PAS
  325.  
  326.   EmsExist
  327.   ---------------------------------------------------------------------
  328.      Purpose:  Determine whether EMS services exist or not
  329.  
  330.      Syntax:
  331.        [C/C++] extern unsigned char cdecl EmsExist(void);
  332.       [QB/PDS] DECLARE FUNCTION EmsExist% ()
  333.           [TP] Function EmsExist : Boolean;
  334.          [ASM] extrn EmsExist:far
  335.  
  336.      Remarks:  This routine is needed if you wish to load a module into
  337.                EMS memory. The module loading routines do not detect
  338.                whether EMS is available or not, and will not use EMS if
  339.                not told to. If told to, and EMS services are not really
  340.                available (ie, didn't use this detection routine), the
  341.                machine will probably lock up.
  342.  
  343.      Calling:  none
  344.  
  345.      Returns:
  346.          ax    EmsExist    - EMS Exist Flag: 0- EMS services not found
  347.                                              1- EMS services available
  348.  
  349.      See Also: LoadGDM
  350.  
  351.      Source:   C_MSE.ASM, EMS.ASM, MSE_TP.PAS
  352.  
  353.      Example:  MMP.BAS, PLAYC.C, GDMPLAY.PAS
  354.  
  355.   FreeMSE
  356.   ---------------------------------------------------------------------
  357.      Purpose:  Deallocate MSE memory and unload MSE file
  358.  
  359.      Syntax:
  360.        [C/C++] extern void cdecl FreeMSE(void);
  361.       [QB/PDS] DECLARE SUB FreeMSE ()
  362.           [TP] Procedure FreeMSE;
  363.          [ASM] extrn FreeMSE:far
  364.  
  365.      Remarks:  This function is called to unload the current MSE so
  366.                that you could either exit your program or possibly load
  367.                a different MSE file (using LoadMSE). It will disable
  368.                sound output if needed, deallocate all MSE memory
  369.                (including music and sound effects), and unload the MSE.
  370.  
  371.                After this is called, do *not* use any of the other MSE
  372.                functions (except LoadMSE) because this will result in a
  373.                system crash or reboot.
  374.  
  375.      Calling:  none
  376.  
  377.      Returns:  none
  378.  
  379.      See Also: LoadMSE
  380.  
  381.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM, MSE_TP.PAS
  382.  
  383.      Example:  See example of LoadMSE
  384.  
  385.   FreeSample
  386.   ---------------------------------------------------------------------
  387.      Purpose:  Frees a sample slot and deallocates its memory
  388.  
  389.      Syntax:
  390.        [C/C++] extern int cdecl FreeSample(unsigned char SamNum);
  391.       [QB/PDS] DECLARE FUNCTION FreeSample% (SamNum%)
  392.           [TP] Function FreeSample(SamNum : Byte) : Word;
  393.          [ASM] extrn FreeSample:far
  394.  
  395.      Remarks:  You can not free sample slots used by the currently
  396.                loaded music module.
  397.  
  398.      Calling:
  399.          cl    SamNum      - Sample slot number to free sample from.
  400.                (0..255)
  401.  
  402.      Returns:
  403.          ax    FreeSample  - Error code:
  404.                              0 - No error
  405.                              1 - Sample slot isn't used
  406.                              2 - Can not free module sample
  407.  
  408.      See Also: AllocSample
  409.  
  410.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  411.  
  412.      Example:  none
  413.  
  414.   GetChannelTable
  415.   ---------------------------------------------------------------------
  416.      Purpose:  Get extended information on a sound or music channel
  417.  
  418.      Syntax:
  419.        [C/C++] extern void cdecl GetChannelTable(char Channel,
  420.                int TSeg, int TOff);
  421.       [QB/PDS] DECLARE SUB GetChannelTable (Channel%, TSeg%, TOff%)
  422.           [TP] Procedure GetChannelTable(Channel : Byte; TSeg,
  423.                TOff : Word);
  424.          [ASM] extrn GetChannelTable:far
  425.  
  426.      Remarks:  This routine is more of a hack job than anything, in the
  427.                future it will most likely be replaced by some more
  428.                eloquent functions.
  429.  
  430.      Calling:
  431.          bl    Channel     - Digital channel to get information on.
  432.                (1..32)
  433.          dx    TSeg        - Segment of 128 byte buffer to hold the
  434.                              channel information. Format of this is
  435.                              declared in CHANTYPE.BI (QB/PDS) or
  436.                              CHANTYPE.H (C/C++).
  437.          di    TOff        - Offset of 128 byte buffer to hold channel
  438.                              information.
  439.  
  440.      Returns:
  441.                ChanTab     - Now filled with information on the desired
  442.                              channel.
  443.  
  444.      See Also: GetSampleTable
  445.  
  446.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  447.  
  448.      Example:  CHPLAY.C
  449.  
  450.   GetMainScope
  451.   ---------------------------------------------------------------------
  452.      Purpose:  Get currently played sample from the mixing buffer
  453.  
  454.      Syntax:
  455.        [C/C++] extern void cdecl GetMainScope(unsigned int *Left,
  456.                unsigned int *Right);
  457.       [QB/PDS] DECLARE SUB GetMainScope (Left%, Right%)
  458.           [TP] Procedure GetMainScope(Var Left, Right : Word);
  459.          [ASM] extrn GetMainScope:far
  460.  
  461.      Remarks:  Values from this are useful in creating a digital output
  462.                scope (showing the sound's waveform).
  463.  
  464.                If the current sound device has one 8 bits output, the
  465.                sample will be multiplied by 256 so that it fits in a 16
  466.                bit number.
  467.  
  468.      Calling:  none
  469.  
  470.      Returns:
  471.          ax    Left        - Currently played sample on left speaker.
  472.                (0..FFFFh)
  473.          cx    Right       - Currently played sample on right speaker.
  474.                (0..FFFFh)
  475.  
  476.      See Also: none
  477.  
  478.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  479.  
  480.      Example:  GDMSCOPE.PAS
  481.  
  482.   GetSampleTable
  483.   ---------------------------------------------------------------------
  484.      Purpose:  Get extended information on a digital sample
  485.  
  486.      Syntax:
  487.        [C/C++] extern void cdecl GetSampleTable(unsigned char Sample,
  488.                int TSeg, int TOff);
  489.       [QB/PDS] DECLARE SUB GetSampleTable (Sample%, TSeg%, TOff%)
  490.           [TP] Procedure GetSampleTable(Sample : Byte; TSeg,
  491.                TOff : Word);
  492.          [ASM] extrn GetSampleTable:far
  493.  
  494.      Remarks:  This routine is more of a hack job than anything, in the
  495.                future it will most likely be replaced by some more
  496.                eloquent functions.
  497.  
  498.      Calling:
  499.          bl    Sample      - Sample number to get information on.
  500.                (0..255)
  501.          dx    TSeg        - Segment of 64 byte buffer to hold the
  502.                              sample information. Format is declared in
  503.                              GDMTYPE.BI or GDMTYPE.H.
  504.          di    TOff        - Offset of 64 byte buffer to hold the
  505.                              sample information.
  506.  
  507.      Returns:  SamTable    - Now filled with information on the desired
  508.                              channel.
  509.  
  510.      See Also: GetChannelTable
  511.  
  512.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  513.  
  514.      Example:  none
  515.  
  516.   LoadGDM
  517.   ---------------------------------------------------------------------
  518.      Purpose:  Load a GDM module from disk into MSE memory
  519.  
  520.      Syntax:
  521.        [C/C++] extern void cdecl LoadGDM(int Handle, long FileOff,
  522.                int *Flags, GDMHeader *gdmhead);
  523.       [QB/PDS] DECLARE SUB LoadGDM (Handle%, FileOff&, Flags%,_
  524.                GDMHeadSeg, GDMHeadOff)
  525.           [TP] Function LoadGDM(Var Handle : File; FileOff : Longint;
  526.                Var Flags : Word; Var GDMHead) : Word;
  527.          [ASM] extrn LoadGDM:far
  528.  
  529.      Remarks:  GDMHead is a type structure defined in the file
  530.                GDMTYPE.BI, GDMTYPE.H, and MSE_TP.PAS.
  531.  
  532.                Before you can play music or any sound effects, you must
  533.                load a module from disk. Use this routine to load GDMs
  534.                (converted from another format with the 2GDM utility).
  535.  
  536.      Calling:
  537.          ax    Handle      - File handle number of a previously opened
  538.                              file (the GDM to load) in BINARY mode.
  539.  
  540.                    [QB/PDS]  Basic doesn't use DOS file handles like
  541.                              BWSB requires. To get a DOS file handle
  542.                              from Basic's file handles, use the
  543.                              FILEATTR function.
  544.          ecx   FileOff     - Offset into the file to start loading the
  545.                              module from (for playing modules within
  546.                              EXEs, etc).
  547.          bl    Flag        - Loading flags. Currently only bit 0 is
  548.                              used.                   [NO EFFECT ON GUS]
  549.                              0 - Load into base memory only
  550.                              1 - Load into EMS memory (must be present)
  551.  
  552.      Returns:
  553.          dx:di GDMHead     - Now filled with information from the
  554.                              module. Use this to find things like the
  555.                              module's title, etc.
  556.          bl    Flag        - Module load error code:
  557.                              0 - No errors, module loaded successfully.
  558.                              1 - Module is corrupt
  559.                              2 - Could not autodetect module type (N/A)
  560.                              3 - Bad file format ID string
  561.                              4 - Insufficient memory to load module
  562.                              5 - Can not unpack samples
  563.                              6 - AdLib instruments not supported
  564.  
  565.                              If you get back any error code other than
  566.                              0, do *not* enable music processing. If
  567.                              you do, you'll probably end up crashing
  568.                              the system.
  569.  
  570.      See Also: UnloadModule
  571.  
  572.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  573.  
  574.      Example:
  575.      [C/C++]-----------------------------------------------------------
  576.      #include <bwsb.h>                  // always need this!
  577.  
  578.      #include <stdio.h>
  579.      #include <io.h>
  580.      #include <fcntl.h>
  581.      void main(void)
  582.      {  int ErrorFlag, Handle;
  583.         int BaseIO = { 0xFFFF };
  584.         int IRQ = { 0xFF };
  585.         int DMA = { 0xFF };
  586.         GDMHeader ModHead;
  587.  
  588.         ErrorFlag = LoadMSE("SB1X.MSE", 0, 45, 4096,
  589.                             &BaseIO, &IRQ, &DMA);
  590.         if (ErrorFlag)
  591.         {  printf("Error while loading MSE: %u\n", ErrorFlag);
  592.            return;                                              }
  593.  
  594.         if ((Handle = open("TUNE.GDM", O_RDONLY | O_BINARY)) == -1)
  595.         {  printf("Can't find file TUNE.GDM\n");
  596.            return;                                              }
  597.  
  598.         printf("Loading module TEST.GDM\n");
  599.         ErrorFlag = EmsExist && 1;      // Enable EMS use if available
  600.         LoadGDM(Handle, 0, &ErrorFlag, &ModHead);
  601.         close(Handle);
  602.  
  603.         switch(ErrorFlag)
  604.         {  case 0:  printf("Finished loading module..\n");
  605.                     break;
  606.            case 1:  printf("Module is corrupt\n");
  607.                     return;
  608.            case 2:  printf("Could not autodetect module type\n");
  609.                     return;
  610.            case 3:  printf("Bad format ID\n");
  611.                     return;
  612.            case 4:  printf("Out of memory\n");
  613.                     return;
  614.            case 5:  printf("Cannot unpack samples\n");
  615.                     return;
  616.            case 6:  printf("AdLib samples not supported\n");
  617.                     return;
  618.            default: printf("Unknown load error: %u\n", ErrorFlag);
  619.                     return;                                     }
  620.         printf("Song: %.32s\n", ModHead.SongTitle);
  621.  
  622.         UnloadModule();                 // Remove module from memory
  623.         FreeMSE();                      // Remove MSE from memory
  624.      }
  625.  
  626.   LoadMSE
  627.   ---------------------------------------------------------------------
  628.      Purpose:  Load and initialize the specified MSE file
  629.  
  630.      Syntax:
  631.        [C/C++] extern int cdecl LoadMSE(char *MSE, unsigned long
  632.                FileOff, unsigned char OverRate, int BufferSize,
  633.                int *Addr, int *IRQ, int *DMA);
  634.       [QB/PDS] DECLARE FUNCTION LoadMSE% (MSE$, FileOff&, OverRate%,_
  635.                BufferSize%, Addr%, IRQ%, DMA%)
  636.           [TP] Function LoadMSE(MSE : String; FileOff : Longint;
  637.                OverRate, BufferSize : Word; Var Addr : Word; Var IRQ,
  638.                DMA : Byte) : Word;
  639.          [ASM] extrn LoadMSE:far
  640.      Remarks:  LoadMSE *must* be called before any of the other
  641.                routines are used. Calling other routines before using
  642.                this one will result in a system crash or reboot.
  643.  
  644.                After LoadMSE is called, you can do any other MSE
  645.                function calls that you want, however, sound output is
  646.                not enabled until you call StartOutput.
  647.  
  648.                The reason for this is that having sound output enabled
  649.                uses additional CPU time at all times to keep the output
  650.                stream moving (except on GUS cards). By keeping these
  651.                two functions separate, you can allow MSE calls and
  652.                still use the full CPU power while doing such things as
  653.                loading music files, etc, which do not need sound output
  654.                to be enabled.
  655.  
  656.      Calling:
  657.          ds:bx MSE         - Path and file name of the MSE file you
  658.                              wish to use.
  659.          edi   FileOff     - File offset to begin loading from. This is
  660.                              useful for using MSEs that have been
  661.                              tacked onto the end of your EXE file or a
  662.                              large data file.
  663.          ah    OverRate    - xxKHz oversampling rate you wish to use.
  664.                (4..48)       Higher oversampling rates provide higher
  665.                              sound fidelity, but uses up more CPU time
  666.                              to do so.
  667.  
  668.                              This value is ignored on the GUS.
  669.          al    BufferSize  - This is the size of the mixing buffer you
  670.                (256..32767)  want to use for the MSE. Larger buffers
  671.                              take more memory and stops foreground
  672.                              execution for longer amounts of time, but
  673.                              causes less clicks and reverberation.
  674.                              Smaller buffers take less memory, but tend
  675.                              to use more CPU time overall and have a
  676.                              greater tendency to reverberate during CPU
  677.                              intensive tasks such as disk access, etc.
  678.                              Experiment and see what works best for
  679.                              your specific application.
  680.  
  681.                              This value is ignored on the GUS.
  682.          dx    Addr        - Base I/O address of the sound card in use.
  683.                              Use the value FFFFh for autodetection.
  684.          ch    IRQ         - IRQ level of the sound card in use. Use
  685.                              the value FFh for autodetection.
  686.          cl    DMA         - DMA channel of sound card in use. Use the
  687.                              value FFh for autodetection.
  688.  
  689.      Returns:
  690.          dx    Addr        - Actual base I/O address used (useful when
  691.                              using autodetection)
  692.          ch    IRQ         - Actual IRQ level used.
  693.          cl    DMA         - Actual DMA channel used.
  694.          ax    ErrCd       - MSE installation error code:
  695.                              0 - No error, MSE installation successful
  696.                              1 - Base I/O address autodetection failure
  697.                              2 - IRQ level autodetection failure
  698.                              3 - DMA channel autodetection failure
  699.                              4 - DMA channel not supported
  700.                              5 - n/a
  701.                              6 - Sound device does not respond
  702.                              7 - Memory control blocks destroyed
  703.                              8 - Insufficient memory for mixing buffers
  704.                              9 - Insufficient memory for MSE file
  705.                              10- MSE has invalid identification string
  706.                              11- MSE disk read failure
  707.                              12- MVSOUND.SYS not loaded
  708.                              13- Insufficient memory for volume table
  709.  
  710.      See Also: FreeMSE
  711.  
  712.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  713.  
  714.      Example:
  715.      [C/C++]-----------------------------------------------------------
  716.      #include <bwsb.h>
  717.  
  718.      #include <stdio.h>
  719.      void main(void)
  720.      {  int ErrorFlag, Handle;
  721.         int BaseIO = { 0xFFFF };
  722.         int IRQ = { 0xFF };
  723.         int DMA = { 0xFF };
  724.         GDMHeader ModHead;
  725.  
  726.         ErrorFlag = LoadMSE("SB1X.MSE", 0, 45, 4096,
  727.                             &BaseIO, &IRQ, &DMA);
  728.         switch (ErrorFlag)
  729.         {  case 0:  break;
  730.            case 1:  printf("Base I/O address autodetection failure\n");
  731.                     return;
  732.            case 2:  printf("IRQ level autodetection failure\n");
  733.                     return;
  734.            case 3:  printf("DMA channel autodetection failure\n");
  735.                     return;
  736.            case 4:  printf("DMA channel not supported\n");
  737.                     return;
  738.            case 6:  printf("Sound device does not respond\n");
  739.                     return;
  740.            case 7:  printf("Memory control blocks destroyed\n");
  741.                     return;
  742.            case 8:  printf("Insufficient memory for mixing buffers\n");
  743.                     return;
  744.            case 9:  printf("Insufficient memory for MSE file\n");
  745.                     return;
  746.            case 10: printf("MSE has invalid identification string\n");
  747.                     return;
  748.            case 11: printf("MSE disk read failure\n");
  749.                     return;
  750.            case 12: printf("MVSOUND.SYS not loaded\n");
  751.                     return;
  752.            case 13: printf("Insufficient memory for volume table\n");
  753.                     return;
  754.            default: printf("Unknown MSE load error: %u\n", ErrorFlag);
  755.                     return;                                     }
  756.         printf("Sound Device: %.20s\n", DeviceName());
  757.  
  758.         FreeMSE();                      // Remove MSE from memory
  759.      }
  760.  
  761.   MixForground
  762.   ---------------------------------------------------------------------
  763.      Purpose:  Mix a new sound buffer when MixStatus <> 0
  764.  
  765.      Syntax:
  766.        [C/C++] extern void cdecl MixForground(void);
  767.       [QB/PDS] DECLARE SUB MixForground ()
  768.           [TP] Procedure MixForground;
  769.          [ASM] extrn MixForground:far
  770.  
  771.      Remarks:  This function should only be used when you have selected
  772.                foreground mixing using the SetAutoMix routine. When the
  773.                MixStatus function turns nonzero, you should call this
  774.                routine ASAP so that sound output will remain smooth and
  775.                unreverberated.
  776.  
  777.                When using foreground mixing, it is best to use a larger
  778.                mixing buffer than normally. This will give you more time
  779.                in between needed calls to MixForground. See LoadMSE for
  780.                more details on setting the mixing buffer size.
  781.  
  782.                This has no effect on the GUS since the GUS does all
  783.                it's mixing in the background by itself.
  784.  
  785.      Calling:  none
  786.  
  787.      Returns:  none
  788.  
  789.      See Also: SetAutoMix, MixStatus, LoadMSE
  790.  
  791.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  792.  
  793.      Example:
  794.      [C/C++]-----------------------------------------------------------
  795.      #include <bwsb.h>
  796.  
  797.      #include <stdio.h>
  798.      #include <conio.h>
  799.      #include <io.h>
  800.      #include <fcntl.h>
  801.      void main(void)
  802.      {  int ErrorFlag, Handle, j;
  803.         int Channels = { 0 };
  804.         int BaseIO = { 0xFFFF };
  805.         int IRQ = { 0xFF };
  806.         int DMA = { 0xFF };
  807.         GDMHeader ModHead;
  808.  
  809.         // Please note that when using foreground mixing, we use a
  810.         // larger mixing buffer (8192 bytes in this case).
  811.         ErrorFlag = LoadMSE("SB1X.MSE", 0, 45, 8192,
  812.                             &BaseIO, &IRQ, &DMA);
  813.  
  814.         if (ErrorFlag)
  815.         {  printf("Error while loading MSE: %u\n", ErrorFlag);
  816.            return;                                              }
  817.  
  818.         if ((Handle = open("TEST.GDM", O_RDONLY | O_BINARY)) == -1)
  819.         {  printf("Can't find file TEST.GDM\n");
  820.            return;                                              }
  821.  
  822.         ErrorFlag = EmsExist && 1;      // Enable EMS use if available
  823.         LoadGDM(Handle, 0, &ErrorFlag, &ModHead);
  824.         close(Handle);
  825.  
  826.         if (ErrorFlag)
  827.         {  printf("Error while loading GDM: %u\n", ErrorFlag);
  828.            return;                                              }
  829.  
  830.         // Scan and count number of used music channels
  831.         // 0xFF is an unused channel, so only inc when not = 0xFF
  832.         for (j = 0;j < 32;j++)
  833.           if (ModHead.PanMap[j] != 0xFF) Channels++;
  834.  
  835.         StartOutput(Channels, 0);       // Enable sound output with
  836.                                         // no amplification.
  837.  
  838.         StartMusic();                   // Start playing the music
  839.         printf("Music should now be playing\n");
  840.         printf("Press any key to stop music..\n");
  841.  
  842.         SetAutoMix(0);                  // Disable background mixing
  843.  
  844.         while(!kbhit())                 // Loop until a key is pressed
  845.         {  if (MixStatus())             // Is mixing needed?
  846.              MixForground();        }   // Yes, call the mixing routine
  847.  
  848.         getch();                        // Clear the keyboard buffer
  849.  
  850.         StopMusic();                    // Stop playing music
  851.         printf("Music has been stopped\n");
  852.  
  853.         StopOutput();                   // Disable sound output
  854.         UnloadModule();                 // Remove module from memory
  855.         FreeMSE();                      // Remove MSE from memory
  856.      }
  857.  
  858.  
  859.   MixStatus
  860.   ---------------------------------------------------------------------
  861.      Purpose:  Get the current mixing demand flag
  862.  
  863.      Syntax:
  864.        [C/C++] extern int cdecl MixStatus(void);
  865.       [QB/PDS] DECLARE FUNCTION MixStatus% ()
  866.           [TP] Function MixStatus : Word;
  867.          [ASM] extrn MixStatus:far
  868.  
  869.      Remarks:  This function is used in conjunction with the
  870.                MixForground routine to do all sound mixing in the
  871.                foreground instead of the background automatically.
  872.                Before you can use this, you must disable background
  873.                mixing using the SetAutoMix routine.
  874.  
  875.                This has no effect on the GUS.
  876.  
  877.      Calling:  none
  878.  
  879.      Returns:
  880.          ax    MixStatus   - Mix demand flag:
  881.                              0 - No mixing currently needed
  882.                              1 - Mixing needed, call MixForground
  883.  
  884.      See Also: SetAutoMix, MixForground
  885.  
  886.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  887.  
  888.      Example:  none
  889.  
  890.   MusicBPM
  891.   ---------------------------------------------------------------------
  892.      Purpose:  Get or set current music BPM (Beat Per Minute) speed
  893.  
  894.      Syntax:
  895.        [C/C++] extern unsigned char cdecl MusicBPM(unsigned char
  896.                NewBPM);
  897.       [QB/PDS] DECLARE FUNCTION MusicBPM% (NewBPM%)
  898.           [TP] Function MusicBPM(NewBPM : Byte) : Byte;
  899.          [ASM] extrn MusicBPM:far
  900.  
  901.      Remarks:  The default BPM speed for a MOD is 125.
  902.  
  903.      Calling:
  904.          ah    NewBPM      - New BPM speed to use. Value of 0 does not
  905.                (0, 32..255)  change the current BPM.
  906.  
  907.      Returns:
  908.          ax    MusicBPM    - The current BPM speed in use.
  909.                (32..255)
  910.  
  911.      See Also: MusicTempo
  912.  
  913.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  914.  
  915.      Example:  See example for MixForground
  916.  
  917.   MusicLoop
  918.   ---------------------------------------------------------------------
  919.      Purpose:  Get number of times music looped/Set music loop enable
  920.  
  921.      Syntax:
  922.        [C/C++] extern unsigned char cdecl MusicLoop(unsigned char
  923.                LoopEnable);
  924.       [QB/PDS] DECLARE FUNCTION MusicLoop% (LoopEnable%)
  925.           [TP] Function MusicLoop(LoopEnable : Byte) : Byte;
  926.          [ASM] extrn MusicLoop:far
  927.  
  928.      Remarks:  none
  929.  
  930.      Calling:
  931.          ah    LoopEnable  - Enable/disable music looping:
  932.                               0 - Music looping disabled. When last
  933.                                   order is playing, music processing
  934.                                   will be disabled. Use StartMusic to
  935.                                   reenable.
  936.                    [default]  1 - Music looping enabled. When last
  937.                                   order number is finished, music will
  938.                                   loop back to order zero.
  939.                              FFh- Don't set the loop enable/disable
  940.                                   flag.
  941.  
  942.      Returns:
  943.          ax    MusicLoop   - Number of times the music has looped
  944.                (0..255)
  945.  
  946.      See Also: StartMusic, MusicStatus, StopMusic
  947.  
  948.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  949.  
  950.      Example:  See example for MusicOrder
  951.  
  952.   MusicStatus
  953.   ---------------------------------------------------------------------
  954.      Purpose:  Get the current music enable status
  955.  
  956.      Syntax:
  957.        [C/C++] extern unsigned char cdecl MusicStatus(void);
  958.       [QB/PDS] DECLARE FUNCTION MusicStatus% ()
  959.           [TP] Function MusicStatus : Word;
  960.          [ASM] extrn MusicStatus:far
  961.  
  962.      Remarks:  none
  963.  
  964.      Calling:  none
  965.  
  966.      Returns:
  967.          ax    MusicStatus - Current music enabled flag:
  968.                              0 - Music is disabled (StopMusic)
  969.                              1 - Music is enabled (StartMusic was
  970.                                  called earlier)
  971.  
  972.      See Also: StartMusic, StopMusic
  973.  
  974.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  975.  
  976.      Example:  See example for MixForground
  977.  
  978.   MusicOrder
  979.   ---------------------------------------------------------------------
  980.      Purpose:  Get or set the current playing order position
  981.  
  982.      Syntax:
  983.        [C/C++] extern unsigned char cdecl MusicOrder(unsigned char
  984.                NewOrder);
  985.       [QB/PDS] DECLARE FUNCTION MusicOrder% (NewOrder%)
  986.           [TP] Function MusicOrder(NewOrder : Byte) : Byte;
  987.          [ASM] extrn MusicOrder:far
  988.  
  989.      Remarks:  This is the routine you'll probably be wanting to use to
  990.                move around in modules rather than MusicPattern.
  991.  
  992.      Calling:
  993.          ah    NewOrder    - New order position to start playing from.
  994.                (0..FFh)      FFh does not change the order position.
  995.  
  996.                              Trying to play an order number that does
  997.                              not exist will play pattern number 0.
  998.  
  999.      Returns:
  1000.          ax    MusicOrder  - Order position actually in use.
  1001.  
  1002.      See Also: MusicPattern, MusicRow
  1003.  
  1004.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1005.  
  1006.      Example:
  1007.      [C/C++]----------------------------------------------------------
  1008.      #include <bwsb.h>
  1009.  
  1010.      #include <stdio.h>
  1011.      #include <conio.h>
  1012.      #include <io.h>
  1013.      #include <fcntl.h>
  1014.      void main(void)
  1015.      {  int ErrorFlag, Handle, j;
  1016.         int Channels = { 0 };
  1017.         int BaseIO = { 0xFFFF };
  1018.         int IRQ = { 0xFF };
  1019.         int DMA = { 0xFF };
  1020.         char PlayString[] =
  1021.         { "Playing ──> Order: %u  Pattern: %u  Row: %u  Loops: %u  \r"
  1022.         };
  1023.         GDMHeader ModHead;
  1024.  
  1025.         ErrorFlag = LoadMSE("SB1X.MSE", 0, 45, 4096,
  1026.                             &BaseIO, &IRQ, &DMA);
  1027.         if (ErrorFlag)
  1028.         {  printf("Error while loading MSE: %u\n", ErrorFlag);
  1029.            return;                                              }
  1030.  
  1031.         if ((Handle = open("TEST.GDM", O_RDONLY | O_BINARY)) == -1)
  1032.         {  printf("Can't find file TEST.GDM\n");
  1033.            return;                                              }
  1034.  
  1035.         ErrorFlag = EmsExist && 1;      // Enable EMS use if available
  1036.         LoadGDM(Handle, 0, &ErrorFlag, &ModHead);  close(Handle);
  1037.         if (ErrorFlag)
  1038.         {  printf("Error while loading GDM: %u\n", ErrorFlag);
  1039.            return;                                              }
  1040.  
  1041.         // Scan and count number of used music channels
  1042.         // 0xFF is an unused channel, so only inc when not = 0xFF
  1043.         for (j = 0;j < 32;j++)
  1044.           if (ModHead.PanMap[j] != 0xFF) Channels++;
  1045.  
  1046.         StartOutput(Channels, 0);       // Enable sound output
  1047.         StartMusic();                   // Start playing the music
  1048.  
  1049.         while(!kbhit())                 // Loop until a key is pressed
  1050.         {  printf(PlayString,
  1051.                   MusicOrder(0xFF),     // Order number playing
  1052.                   MusicPattern(0xFF),   // Pattern number playing
  1053.                   MusicRow(),           // Row number playing
  1054.                   MusicLoop(0xFF));  }  // Times music has restarted
  1055.  
  1056.         getch();                        // Clear the keyboard buffer
  1057.  
  1058.         StopMusic();                    // Stop playing music
  1059.         StopOutput();                   // Disable sound output
  1060.         UnloadModule();                 // Remove module from memory
  1061.         FreeMSE();                      // Remove MSE from memory
  1062.      }
  1063.  
  1064.   MusicPattern
  1065.   ---------------------------------------------------------------------
  1066.      Purpose:  Get or set the current playing pattern number
  1067.  
  1068.      Syntax:
  1069.        [C/C++] extern unsigned char cdecl MusicPattern(unsigned char
  1070.                NewPattern);
  1071.       [QB/PDS] DECLARE FUNCTION MusicPattern% (NewPattern%)
  1072.           [TP] Function MusicPattern(NewPattern : Byte) : Byte;
  1073.          [ASM] extrn MusicPattern:far
  1074.  
  1075.      Remarks:  You will usually not use this function to set the
  1076.                pattern position, use MusicOrder instead.
  1077.  
  1078.      Calling:
  1079.          ah    NewPattern  - New pattern number to play. FFh does not
  1080.                (0..FFh)      change pattern number (you will want that
  1081.                              in most cases).
  1082.  
  1083.                              Selecting a pattern that does not exist
  1084.                              will most likely crash the system.
  1085.  
  1086.      Returns:
  1087.          ax    MusicPattern- Current playing pattern number.
  1088.  
  1089.      See Also: MusicRow, MusicOrder
  1090.  
  1091.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1092.  
  1093.      Example:  See example for MusicOrder
  1094.  
  1095.   MusicRow
  1096.   ---------------------------------------------------------------------
  1097.      Purpose:  Get the current playing row number
  1098.  
  1099.      Syntax:
  1100.        [C/C++] extern unsigned char cdecl MusicRow(void);
  1101.       [QB/PDS] DECLARE FUNCTION MusicRow% ()
  1102.           [TP] Function MusicRow : Byte;
  1103.          [ASM] extrn MusicRow:far
  1104.  
  1105.      Remarks:  There is currently no way to set the current row.
  1106.  
  1107.      Calling:  none
  1108.  
  1109.      Returns:
  1110.          ax    MusicRow    - Current playing row number.
  1111.  
  1112.      See Also: MusicPattern, MusicOrder
  1113.  
  1114.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1115.  
  1116.      Example:  See example for MusicOrder
  1117.  
  1118.   MusicTempo
  1119.   ---------------------------------------------------------------------
  1120.      Purpose:  Get or set the current music tempo
  1121.  
  1122.      Syntax:
  1123.        [C/C++] extern unsigned char cdecl MusicTempo(unsigned char
  1124.                NewTempo);
  1125.       [QB/PDS] DECLARE FUNCTION MusicTempo% (NewTempo%)
  1126.           [TP] Function MusicTempo(NewTempo : Byte) : Byte;
  1127.          [ASM] extrn MusicTempo:far
  1128.  
  1129.      Remarks:  The default tempo for a MOD is 6.
  1130.  
  1131.      Calling:
  1132.          ah    NewTempo    - New tempo value to use. Value of FFh does
  1133.                (FFh, 0..254) not change the current tempo.
  1134.  
  1135.      Returns:
  1136.          ax    MusicTempo  - Tempo setting actually in use.
  1137.  
  1138.      See Also: MusicBPM
  1139.  
  1140.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1141.  
  1142.      Example:  none
  1143.  
  1144.   MusicVolume
  1145.   ---------------------------------------------------------------------
  1146.      Purpose:  Get or set the global music volume
  1147.  
  1148.      Syntax:
  1149.          [C++] extern unsigned char cdecl MusicVolume(unsigned char
  1150.                Vol);
  1151.       [QB/PDS] DECLARE FUNCTION MusicVolume% (Vol%)
  1152.           [TP] Function MusicVolume(Vol : Byte) : Byte;
  1153.          [ASM] extrn MusicVolume:far
  1154.  
  1155.      Remarks:  The global music volume is by default set to 64 by any
  1156.                of the module loading routines, except for S3Ms, which
  1157.                are set to the default specified in the module.
  1158.  
  1159.      Calling:
  1160.          ah    Vol         - New global music volume to use. FFh does
  1161.                (FFh, 0..64)  not change the global music volume.
  1162.  
  1163.      Returns:
  1164.          ax    MusicVolume - The current global music volume.
  1165.                (0..64)
  1166.  
  1167.      See Also: none
  1168.  
  1169.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1170.  
  1171.      Example:  none
  1172.  
  1173.   PlaySample
  1174.   ---------------------------------------------------------------------
  1175.      Purpose:  Play a sound effect already loaded into MSE memory
  1176.  
  1177.      Syntax:
  1178.        [C/C++] extern void cdecl PlaySample(unsigned char Channel,
  1179.                unsigned char Sample, unsigned int Rate, unsigned char
  1180.                Vol, unsigned char Pan);
  1181.       [QB/PDS] DECLARE SUB PlaySample (Channel%, Sample%, Rate&, Vol%,_
  1182.                Pan%)
  1183.           [TP] Procedure PlaySample(Channel, Sample : Byte; Rate :
  1184.                Word; Vol, Pan : Byte);
  1185.          [ASM] extrn PlaySample:far
  1186.  
  1187.      Remarks:  This is for playing sound effects in your programs. It
  1188.                is a rather tedious routine to master, so consult the
  1189. F->            tutorial (BWSB.DOC) for more help.
  1190.  
  1191.      Calling:
  1192.          bl    Channel     - Sound channel to play the sound effect on.
  1193.                (1..32)       If you play on a channel that is used by
  1194.                              the music, you'll make the music skip or
  1195.                              cut off notes randomly.
  1196.          cl    Sample      - This is the sample number in the loaded
  1197.                (0..255)      module to play as your sound effect.
  1198.          ax    Rate        - The sampling rate to play the sample at.
  1199.                (4000..44000)
  1200.          dl    Vol         - Volume level to play the sample at.
  1201.                (0..64)       Normally you'll use 64, unless you're
  1202.                              doing a special effect like echoes, etc.
  1203.          dh    Pan         - Pan position between left and right
  1204.                (0..15, FFh)  speakers to play sample at. Note that
  1205.                              values other than 0, 8, and 15 require
  1206.                              additional CPU time (except on GUS):
  1207.  
  1208.                               0 - Left Most     8 - Middle
  1209.                              15 - Right Most  FFh - Use Old Position
  1210.  
  1211.      Returns:  none
  1212.  
  1213.      See Also: none
  1214.  
  1215.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1216.  
  1217.      Example:  SND-PAD.BAS
  1218.  
  1219.   SetAutoMix
  1220.   ---------------------------------------------------------------------
  1221.      Purpose:  Select background mixing or manual foreground mixing
  1222.  
  1223.      Syntax
  1224.        [C/C++] extern void cdecl SetAutoMix(char MixFlag);
  1225.       [QB/PDS] DECLARE SUB SetAutoMix (MixFlag%)
  1226.           [TP] Procedure SetAutoMix(MixFlag : Byte);
  1227.          [ASM] extrn SetAutoMix:far
  1228.  
  1229.      Remarks:  In some cases it is more desirable to having mixing done
  1230.                in the foreground where it can be interrupted rather
  1231.                than in the background where it takes over the PC for
  1232.                the whole duration required to mix the next buffer (like
  1233.                under Windows, for example).
  1234.  
  1235.                In these cases, set the mixing to foreground and then
  1236.                keep a check on the mixing status (MixStatus) and do
  1237.                mixing (MixForground) whenever necessary.
  1238.  
  1239.                This has no effect on the GUS.
  1240.  
  1241.      Calling:
  1242.          al    MixFlag     - 0 - Mix manually in the foreground.
  1243.                              1 - Mix automatically in the background.
  1244.  
  1245.      Returns:  none
  1246.  
  1247.      See Also: MixForground, MixStatus
  1248.  
  1249.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1250.  
  1251.      Example:  See example for MixForground
  1252.  
  1253.   StartMusic
  1254.   ---------------------------------------------------------------------
  1255.      Purpose:  Enable music processing
  1256.  
  1257.      Syntax:
  1258.        [C/C++] extern void cdecl StopMusic(void);
  1259.       [QB/PDS] DECLARE SUB StartMusic ()
  1260.           [TP] Procedure StartMusic;
  1261.          [ASM] extrn StartMusic:far
  1262.  
  1263.      Remarks:  When a module is loaded and sound output is enabled, so
  1264.                can start the module playback using this function. Until
  1265.                music is enabled, no music will be played.
  1266.  
  1267.                If you do not have a module loaded (or have a corrupted
  1268.                module loaded), enabling music playback will most likely
  1269.                crash the system because no safety checks are done on
  1270.                the music data.
  1271.  
  1272.      Calling:  none
  1273.  
  1274.      Returns:  none
  1275.  
  1276.      See Also: StopMusic, MusicStatus
  1277.  
  1278.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1279.  
  1280.      Example:
  1281.      [C/C++]-----------------------------------------------------------
  1282.      #include <bwsb.h>
  1283.  
  1284.      #include <stdio.h>
  1285.      #include <conio.h>
  1286.      #include <io.h>
  1287.      #include <fcntl.h>
  1288.      void main(void)
  1289.      {  int ErrorFlag, Handle, j;
  1290.         int Channels = { 0 };
  1291.         int BaseIO = { 0xFFFF };
  1292.         int IRQ = { 0xFF };
  1293.         int DMA = { 0xFF };
  1294.         GDMHeader ModHead;
  1295.  
  1296.         ErrorFlag = LoadMSE("SB1X.MSE", 0, 45, 4096,
  1297.                             &BaseIO, &IRQ, &DMA);
  1298.         if (ErrorFlag)
  1299.         {  printf("Error while loading MSE: %u\n", ErrorFlag);
  1300.            return;                                              }
  1301.  
  1302.         if ((Handle = open("TEST.GDM", O_RDONLY | O_BINARY)) == -1)
  1303.         {  printf("Can't find file TEST.GDM\n");
  1304.            return;                                              }
  1305.  
  1306.         ErrorFlag = EmsExist && 1;      // Enable EMS use if available
  1307.         LoadGDM(Handle, 0, &ErrorFlag, &ModHead);  // Load the GDM file
  1308.         close(Handle);
  1309.  
  1310.         if (ErrorFlag)                  // Was there an error loading?
  1311.         {  printf("Error while loading GDM: %u\n", ErrorFlag);
  1312.            return;                                              }
  1313.  
  1314.         // Scan and count number of used music channels
  1315.         // 0xFF is an unused channel, so only inc when not = 0xFF
  1316.         for (j = 0;j < 32;j++)
  1317.           if (ModHead.PanMap[j] != 0xFF) Channels++;
  1318.  
  1319.         StartOutput(Channels, 0);       // Enable sound output with
  1320.                                         // no amplification.
  1321.  
  1322.         StartMusic();                   // Start playing the music
  1323.         printf("Music should now be playing\n");
  1324.         printf("Press any key to stop music..\n");
  1325.  
  1326.         getch();                        // Wait for a keypress to stop
  1327.  
  1328.         StopMusic();                    // Stop playing music
  1329.         printf("Music has been stopped\n");
  1330.  
  1331.         StopOutput();                   // Disable sound output
  1332.         UnloadModule();                 // Remove module from memory
  1333.         FreeMSE();                      // Remove MSE from memory
  1334.      }
  1335.  
  1336.   StartOutput
  1337.   ---------------------------------------------------------------------
  1338.      Purpose:  Initialize and enable the sound output routines
  1339.  
  1340.      Syntax:
  1341.        [C/C++] extern unsigned int cdecl StartOutput(unsigned char
  1342.                Channels, unsigned char Amplify);
  1343.       [QB/PDS] DECLARE FUNCTION StartOutput& (Channels%, Amplify%)
  1344.           [TP] Function StartOutput(Channels, Amplify : ShortInt)
  1345.                : Word;
  1346.          [ASM] extrn StartOutput:far
  1347.  
  1348.      Remarks:  No sound will be playable until sound output is enabled
  1349.                with this routine. When sound output is enabled, a small
  1350.                amount of CPU time is used to keep the output stream
  1351.                flowing, so try to keep sound output enabled *only* when
  1352.                you need to have sound/music playing.
  1353.  
  1354.                If sound output is already enabled, this routine will
  1355.                have no effect.
  1356.  
  1357.      Calling:
  1358.          al    Channels    - Total number of output channels to enable.
  1359.                (1..32)       More output channels require more CPU time
  1360.                              and diminish overall sound quality, so use
  1361.                              as few as possible.
  1362.          n/a   Amplify     - Amplification level. Too high a value will
  1363.                (0..9)        cause clicks and cracks in the output.
  1364.                              Under normal use, use amplification 0. If
  1365.                              you know that a value greater than that
  1366.                              won't cause clicks, by all means use it
  1367.                              because it will increase sound fidelity.
  1368.  
  1369.                              This value is ignored on the GUS.
  1370.  
  1371.      Returns:
  1372.          ax    StartOutput - Actual oversampling rate (in Hz) used.
  1373.  
  1374.      See Also: StopOutput
  1375.  
  1376.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1377.  
  1378.      Example:  See example for StartMusic
  1379.  
  1380.   StopBanner
  1381.   ---------------------------------------------------------------------
  1382.      Purpose:  Disables the signoff banner in the unregistered version
  1383.  
  1384.      Syntax:
  1385.        [C/C++] extern void cdecl StopBanner(void);
  1386.       [QB/PDS] DECLARE SUB StopBanner ()
  1387.           [TP] Procedure StopBanner;
  1388.          [ASM] extrn StopBanner:far
  1389.  
  1390.      Remarks:  This must be called before FreeMSE is called to be
  1391.                effective.
  1392.  
  1393.      Calling:  none
  1394.  
  1395.      Returns:  none
  1396.  
  1397.      See Also: none
  1398.  
  1399.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1400.  
  1401.      Example:  none
  1402.  
  1403.   StopMusic
  1404.   ---------------------------------------------------------------------
  1405.      Purpose:  Disable music processing
  1406.  
  1407.      Syntax:
  1408.        [C/C++] extern void cdecl StopMusic(void);
  1409.       [QB/PDS] DECLARE SUB StopMusic ()
  1410.           [TP] Procedure StopMusic;
  1411.          [ASM] extrn StopMusic:far
  1412.  
  1413.      Remarks:  Stopping the music also saves a tiny amount of CPU time.
  1414.                This routine does *not* turn off all music channels so
  1415.                after this call there will possibly be some samples
  1416.                still playing if any looped samples were being played.
  1417.  
  1418.                Note, you *must* disable music processing before
  1419.                unloading the current module (UnloadModule). Not doing
  1420.                so will probably end up in a system crash at some point
  1421.                later on when music data is overwritten.
  1422.  
  1423.      Calling:  none
  1424.  
  1425.      Returns:  none
  1426.  
  1427.      See Also: StartMusic, MusicStatus
  1428.  
  1429.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1430.  
  1431.      Example:  See example for StartMusic
  1432.  
  1433.   StopOutput
  1434.   ---------------------------------------------------------------------
  1435.      Purpose:  Turns off all sound output processing
  1436.  
  1437.      Syntax:
  1438.        [C/C++] extern void cdecl StopOutput(void);
  1439.       [QB/PDS] DECLARE SUB StopOutput ()
  1440.           [TP] Procedure StopOutput;
  1441.          [ASM] extrn StopOutput:far
  1442.  
  1443.      Remarks:  Once this is called, no more sound can be played until
  1444.                StartOutput is called again. It is generally used to
  1445.                shut off all output while more data is transferred to or
  1446.                from the disk since disk transferring is generally quite
  1447.                a bit slower when sound output is running.
  1448.  
  1449.                If sound output is already off, this routine has no
  1450.                effect.
  1451.  
  1452.      Calling:  none
  1453.  
  1454.      Returns:  none
  1455.  
  1456.      See Also: StartOutput
  1457.  
  1458.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1459.  
  1460.      Example:  See example for StartMusic
  1461.  
  1462.   UnloadModule
  1463.   ---------------------------------------------------------------------
  1464.      Purpose:  Free all memory used by the current music file
  1465.  
  1466.      Syntax:
  1467.        [C/C++] extern void cdecl UnloadModule(void);
  1468.       [QB/PDS] DECLARE SUB UnloadModule ()
  1469.           [TP] Procedure UnloadModule;
  1470.          [ASM] extrn UnloadModule:far
  1471.  
  1472.      Remarks:  This routine must be called before loading a new music
  1473.                file. Once it is called, do not enable music processing,
  1474.                for the music data may get overwritten after this call.
  1475.                In that case, the invalid music data would probably
  1476.                cause a system crash.
  1477.  
  1478.      Calling:  none
  1479.  
  1480.      Returns:  none
  1481.  
  1482.      See Also: LoadGDM
  1483.  
  1484.      Source:   C_MSE.ASM, QBX_MSE.ASM, TPX_MSE.ASM
  1485.  
  1486.      Example:  See example for LoadGDM
  1487.