Sound, Music & MIDI Collection 2/SMMVOL2.bin/PROG/SWMP141.ZIP/ASM.DOC

Text File | 1995-12-12 | 7.4 KB | 162 lines

 ┌────────────────────────────────────────────────────────────────────────────┐
 │ Module Player V1.41     (c) 1994,1995 by Lord Excess of Sound Wizards Int. │
 └────────────────────────────────────────────────────────────────────────────┘



        USING THE SWMP DRIVERS WITH TURBO ASSEMBLER
        ───────────────────────────────────────────
        (or any other language allowing inline asm instructions)


         First you have to unzip the files of archive ASM_SDK.ZIP.
        Files you need in any case are:

          SB.DRV       : SoundBlaster driver      [ 22.2 kHz mono     ]
          SBP.DRV      : SoundBlaster Pro driver  [ 21.7 kHz stereo   ]
          GUS.DRV      : Gravis UltraSound driver [ 44.1 kHz +stereo+ ]
          MODPLAY.LIB  : TASM library that holds all drivers
          MODPLAY.INC  : include file for ModPlay.Lib

         The rest are example files, which can be important to
        understand things better.


         In general you first have to allocate memory and then load one
        of the drivers into RAM (must be a paragraph address). So you
        perhaps will be asking at program start which driver to load.
        After having loaded the selected file, you can use the driver
        by doing far calls to its first address (driver_segment:0000).

         Note: Memory allocation must be available via int 21h,
        subfunction 48h. Therefore you have to adjust your own memory
        control block first, else the drivers cannot alloc mem for the
        soundfiles!

         Convention is that the register BX contains the subfunction
        number, additional parameters are placed in AX,CX,DX etc.
        The following subfunctions are available:


┌──INIT DRIVER─────────────────────────────────────────────────────────────────
│       BX=0, CX,DX=configuration
│           Initialize driver using configuration in CX and DX.
│           Configuration for -SoundBlaster:      CL=IRQ NUMBER, CH=1
│                                                 DX=BASE ADDRESS
│                             -SoundBlaster Pro:  CL=IRQ NUMBER, CH=DMA CHANNEL
│                                                 DX=BASE ADDRESS
│                             -Gravis UltraSound: CL=GF1 IRQ, CH=MIDI IRQ
│                                                 DX=BASE ADDRESS
│        -> Returns AX=driver version if successful, else 0.
│       Note: If the driver was initialized correctly, it HAS TO BE CLOSED
│             at program end using subfunction #1.
└
┌──CLOSE DRIVER────────────────────────────────────────────────────────────────
│       BX=1
│           Close driver, stop playing, put soundcard in a safe state,
│           restore all interrupt vectors etc.
└
┌──LOAD MODULE─────────────────────────────────────────────────────────────────
│       BX=2, DS:DX=filename
│           Stop any sound output and load modulefile stored in ds:dx, which
│           has to end with a zero byte. Does not start playing the song.
│       -> Returns AX=number of channels (4,6,8) if successful, else zero.
└

┌──START MODULE────────────────────────────────────────────────────────────────
│       BX=3
│           Start playing previously loaded song.
└
┌──STOP MODULE─────────────────────────────────────────────────────────────────
│       BX=4
│           Stop any sound output at once.
└
┌──MAIN VOLUME─────────────────────────────────────────────────────────────────
│       BX=5, AL=volume
│           Change mainvolume. Valid values are between 0 (lowest) and
│           64 (loudest).
└
┌──STATUS──────────────────────────────────────────────────────────────────────
│       BX=6
│           Get driver's playing status
│        -> Returns AX=1 if sound is being played, else zero.
└
┌──GET POSITION────────────────────────────────────────────────────────────────
│       BX=7, AL=0
│           Get playing position (to syncronize graphic effects).
│        -> Returns AH=PatternNumber, AL=LineNumber (AX=0 if not playing).
└
┌──SET POSITION────────────────────────────────────────────────────────────────
│       BX=7, AL<>0
│           Set playing position. Value in AL is added to current players
│           pattern position. You cannot step below first and past last
│           pattern. Reasonable values are 1 or -1 (0FFh).
└
┌──PEAKS───────────────────────────────────────────────────────────────────────
│       BX=8, ES:DI=peak buffer
│           Copy the volume settings of each channel to peak buffer, which
│           has to hold a maximum of 8 bytes. The number of channels is
│           known after successful load of modulefile (subfunction #2).
└──────────────────────────────────────────────────────────────────────────────


         All registers will contain the same value after a subfunction
        call, except AX, which will contain anything different from
        zero if the call was successful.

         Using this conventions you can link the drivers in any
        programming language, that supports inline assembly
        instructions.

         TASM users can have things a little bit easier, if using the
        library MODPLAY.LIB. You just have to add the statement

            INCLUDE MODPLAY.INC

         into your asm source and the drivers plus a fully automatic
        hardware detection are linked. This gives you two new procs
        called

            Mod_Driver      : general far call address to drivers
            Mod_End_Seg     : far proc that returns last segment in ax

         The big advantage of this library is that you do not have to
        load drivers into memory. You call Mod_Driver as shown above,
        only the first function is altered slightly containing now the
        option to choose which driver to use:


┌──SELECT AND INIT DRIVER──────────────────────────────────────────────────────
│       BX=0, AX=sounddevice (CX,DX=configuration)
│           Initialize driver selected by register AX. If AX=0 a detection
│           will decide which driver to use, and then try to inizialize it.
│           This should work in most cases. But you have the opportunity to
│           bypass the detection, and manually select and setup the driver.
│           In this case
│              AX=1 stands for SoundBlaster driver
│              AX=2   "     "  SoundBlaster Pro driver
│              AX=3   "     "  Gravis UltraSound driver
│           and CX,DX must hold the configuration as required by the common
│           function #0.
│        -> Returns AX=driver version if successfull, else zero.
└
         The second proc called Mod_End_Seg returns in register AX the
        last segment address of the player to which you can adjust the
        main program's memory control block. The new initialisation
        copies the selected driver to the lowest possible memory
        location (over the first driver) to avoid wasting ram.

┌──GET DRIVER END ADDRESS──────────────────────────────────────────────────────
│        -> Returns AX=driver end segment (unused)
│      Note: Only call this proc after initialisation!
└
         There is also an example file available to illustrate you the
        use of this library. It is coded in very, very easy assembler.
        Of course I do know segment instructions, but this wouldn't
        make the source more readable.


                                               Lord Excess in Dezember '95