home *** CD-ROM | disk | FTP | other *** search
/ TopWare 18: Liquid / Image.iso / liquid / top1120 / sdk.doc < prev    next >
Text File  |  1994-04-10  |  13KB  |  324 lines
  1.  
  2.  
  3.              ----====<   VBE/AI Driver Sample Source Code   >====----
  4.              ----====<  Copyright (c) 1993,1994 VESA, Inc.  >====----
  5.              ----====<          All Rights Reserved         >====----
  6.              ----====<        Version 1.03   04/09/94       >====----
  7.  
  8.  
  9.     INTRODUCTION:
  10.  
  11.         This document describes the VESA VBE/AI Software Developers
  12.         Kit as found on the VBE/AI SDK release diskette. Included
  13.         are sample WAVE drivers for the Pro Audio Spectrum, Disney
  14.         Sound Source, and Sound Blaster cards.  Also included are
  15.         sample MIDI drivers for the OPL2, OPL3 FM chip, and Roland
  16.         MPU-401 MIDI transmitter/receiver.
  17.  
  18.         The VBE/AI specification may be purchased directly from the
  19.         VESA office. To order a copy, call (408)453-0333.
  20.  
  21.         Each body of code is as complete as possible for the 1.00
  22.         revision of the VBE/AI specification. The code may still
  23.         change to match any changes when the specification is
  24.         adopted, or to fix bugs.
  25.  
  26.  
  27.     ADDITIONAL PROGRAMMING NOTES/CLARIFICATIONS:
  28.  
  29.         The Pascal calling conventional permits Pascal functions
  30.         the right to modify the working registers AX, BX, CX, and DX.
  31.         Your code must save these registers, if necessary, before calling
  32.         any of the VBE/AI Pascal function calls.
  33.  
  34.  
  35.     EXAMPLE DRIVERS:
  36.  
  37.         The VBE/AI example drivers were written as DOS TSRs. There
  38.         is one API per TSR. Each one must be loaded separately into
  39.         memory. The program, SETPREF.EXE lets the user assign a
  40.         preference level to each driver.
  41.  
  42.  
  43.     LOADING SAMPLE DRIVERS:
  44.  
  45.         Each driver uses a common set of command line parameters. The
  46.         set looks like this:
  47.  
  48.             /H      helps
  49.             /?      helps
  50.             /B:dd   board # if multiple boards are present
  51.             /A:xx   board address
  52.             /D:xx   dma channel
  53.             /I:dd   irq channel
  54.             /MB:xx  memory base (segment)
  55.             /MR:xx  memory range
  56.             /P:dd   user preference setting
  57.             /U      unload this driver from memory
  58.  
  59.                 dd=decimal #, xx=hex #
  60.  
  61.  
  62.         To load a driver, just run the program. The program decides
  63.         if the hardware is present, then will stay resident. The
  64.         VBE/AI architecture does allow resident TSR drivers to be
  65.         unloaded. Only the first driver loaded will be permenantly
  66.         resident, all others may unload. The available drivers are:
  67.  
  68.             PASWAVE.COM - Pro Audio Spectrum WAVE driver
  69.             SSWAVE.COM  - Disney Sound Source driver
  70.             SBWAVE.COM  - Sound Blaster & Compatible driver
  71.             OPL2.COM    - OPL2 MIDI driver
  72.             MPU.COM     - MPU-401 driver
  73.  
  74.         NOTE: For now, use of the command line switches to setup DMA
  75.         and IRQ settings are required to properly function. In retail
  76.         versions of VBE/AI drivers, the manufacture's installation
  77.         software will make these setup decisions.
  78.  
  79.  
  80.     RUNNING SAMPLE APPLICATIONS:
  81.  
  82.         There are five sample programs currently available in the
  83.         SDK. The source for each program is included on the
  84.         diskette. Two programs test the WAVE drivers, two test the
  85.         MIDI drivers, and the last is a utility for both setting
  86.         user preference levels and displaying the current installed
  87.         driver list.
  88.  
  89.  
  90.     NOTE.EXE
  91.  
  92.         This program allows the user to enter a channel and note
  93.         number to be loaded into the target MIDI device. Once the
  94.         patch has been loaded, a menu of functions will be provided
  95.         to allow the user to turn the note ON or OFF.
  96.  
  97.         To Use:  DOS>note [Pxx]
  98.  
  99.         Where:   [Pxx] is the user preference #.
  100.  
  101.         NOTE: all values are zero based, so the key number ranges
  102.               from 0 to 127. Channels range from 0 to 15. Channel
  103.               number 9 is the percussive channel.
  104.  
  105.     PLAY.EXE
  106.  
  107.         This program accepts a list of up to 10 small (under 64k)
  108.         .WAV files, presents a list to the user, and plays the
  109.         selected file.
  110.  
  111.  
  112.         VESA VBE/AI WAVE Output Program, 01.00
  113.         Copyright (c) 1993,1994  VESA, Inc. All Rights Reserved.
  114.  
  115.         To Use:  DOS>play [file.wav] [file.wav] [file.wav]...
  116.  
  117.         Where: [file.wav] is a list of up to 10 files to play.
  118.  
  119.  
  120.     PMIDI.EXE
  121.  
  122.         This program will play any type 0 or type 1 MIDI file. The
  123.         file must be under 64k in size. Currently, the program
  124.         requires the driver's patch library to be resident in the
  125.         current directory, specfically, OPL2.BNK. This version can
  126.         only handle patch banks under 64K, but will soon support
  127.         unlimited sizes. The following is a dump of the banner and
  128.         command line parameter list:
  129.  
  130.  
  131.         VESA VBE/AI MIDI Output Test Program, 01.00
  132.         Copyright (c) 1993,1994  VESA, Inc. All Rights Reserved.
  133.  
  134.         To Use:  DOS>pmidi [song] [H] [L] [Mxxx] [K{+|-xx}] [R{+|-xx}] [V{xx}]
  135.  
  136.         Where: [song] is the .MID file to be played
  137.            [H]        High end synth playing on channels 1-10.
  138.            [I]        to receive MIDI input only.
  139.            [K{+|-}xx] shifts all key #s up|down by xx count (cheap transpose).
  140.            [L]        Low end synth playing on channels 11-16.
  141.            [Mxxxx]    patch Map file name (256 bytes for 2 tables).
  142.            [Pxx]      selects a VBE device at this (xx) user preference level.
  143.            [R{+|-}xx] shifts all patch #s up|down by xx count.
  144.            [T+|-xx]   Tempo shift faster (+) or (-) slower, in percent.
  145.            [V{xx}]    verbose mode to dump events as they play. xx can be 1-5.
  146.  
  147.  
  148.     SETPREF.EXE
  149.  
  150.         This program allows the user to set his/her preference level
  151.         to each driver. This allows the application to choose which
  152.         driver is the most desirable to use. Also, the program shows
  153.         a listing of the driver configuration. The following is a
  154.         dump of the banner and command line parameter list:
  155.  
  156.  
  157.         VESA VBE/AI Preference setting Program, 01.00
  158.         Copyright (c) 1993,1994  VESA, Inc. All Rights Reserved.
  159.  
  160.         To Use: DOS>SETPREF [H|?] [L] [+] [+xx] [-] [-xxx] [Vxxx]
  161.  
  162.         Where: [L]        lists all devices.
  163.                [+]        increments all preference levels by 1
  164.                [+xxx]     increments a specific devices's preference.
  165.                [-]        decrements all preference levels by 1
  166.                [-xxx]     decrements a specific devices's preference.
  167.                [Vxx]      give a verbose listing of this driver.
  168.  
  169.         NOTE: The highest preference level is zero (0), so incrementing the
  170.               preference actually lowers the user preference, and visa versa.
  171.  
  172.  
  173.     TESTW.EXE
  174.  
  175.         This program tests the WAVE output of a given driver. It
  176.         allows the user to specify a starting block size,
  177.         incremental length, number of times to play the block, and
  178.         more. The program will send the block to the driver, and
  179.         wait for the appropriate callback within a fixed amount of
  180.         time. This time depends upon the sample rate and block size.
  181.         The following is a dump of the banner and command line
  182.         parameter list:
  183.  
  184.  
  185.         VESA VBE/AI WAVE Output Test Program, 01.00
  186.         Copyright (c) 1993,1994  VESA, Inc. All Rights Reserved.
  187.  
  188.         To Use:  DOS>play [16] [Axxx] [Fxxx] [Dxxx] [Ixxx] [Lxxx] [R] [S] [Txxx]
  189.  
  190.         Where: [16] enables 16 bit audio (8 bit is default).
  191.             [Axxx]  uses PlayCont/RecordCont. xxx is an optional block size.
  192.             [Fxxx]  user selects an alternate .WAV/.VOC file by the name of xxx.
  193.             [Dxxx]  allows for delays between blocks of xxx clock ticks (18.2tps).
  194.             [Ixxx]  after each block, Increment the next length by xxx.
  195.             [Lxxx]  block Length of first pcm block.
  196.             [R]     Reload the sample rate after each block finishes.
  197.             [S]     selects Stereo mode operation.
  198.             [Txxx]  number of Times to play the block.
  199.  
  200.  
  201.     TESTR.EXE
  202.  
  203.         This program tests the WAVE input of a given driver. It
  204.         allows the user to specify a starting block size,
  205.         incremental length, number of times to play the block, and
  206.         more. The program will send the block to the driver, and
  207.         wait for the appropriate callback within a fixed amount of
  208.         time. This time depends upon the sample rate and block size.
  209.         The following is a dump of the banner and command line
  210.         parameter list:
  211.  
  212.  
  213.         VESA VBE/AI WAVE Input Test Program, 01.00
  214.         Copyright (c) 1993,1994  VESA, Inc. All Rights Reserved.
  215.  
  216.         To Use:  DOS>rec  [16] [Axxx] [Fxxx] [Dxxx] [Ixxx] [Lxxx] [O{+}] [R] [S] [Txxx]
  217.  
  218.         Where: [16] enables 16 bit audio (8 bit is default).
  219.             [Axxx]  uses PlayCont/RecordCont. xxx is an optional block size.
  220.             [Fxxx]  user selects a new File by the name of xxx.
  221.             [Dxxx]  allows for delays between blocks of xxx clock ticks (18.2tps).
  222.             [Ixxx]  after each block, Increment the next length by xxx.
  223.             [Lxxx]  block Length of first pcm block.
  224.             [O{+}]  Save one recorded block. '+' saves all blocks.
  225.             [R]     Reload the sample rate after each block finishes.
  226.             [S]     selects Stereo mode operation.
  227.             [Txxx]  number of Times to play the block.
  228.  
  229.  
  230.     COMPILING SAMPLE SOURCE CODE:
  231.  
  232.         All the example code was developed using Microsoft 'C' and
  233.         MASM Assember.  Debugging of the TSR's was done using
  234.         Nu-Mega's Soft-ICE and applications using Codeview. To build
  235.         the code, use the included batch files and MAKE files.
  236.         Again, the MAKE files depend upon the above directory
  237.         structure to build the executables. The following list
  238.         describes the files needed to build this driver release:
  239.  
  240.         1. The file 'MKSDK.BAT' executes several MAKE sequences
  241.            to build the VBE/AI SDK program set.
  242.  
  243.         2. The file 'MAKEFILE' is the general make file to
  244.            compile the five sample drivers.
  245.  
  246.         3. The file 'TESTW' is the make file to build the WAVE
  247.            playback (TESTW.EXE) and record (TESTR.EXE) test programs.
  248.  
  249.         4. The file 'PLAY' is the make file to build the WAVE
  250.            playback (PLAY.EXE) program.
  251.  
  252.         5. The file 'PMIDI' is the make file to build the MIDI
  253.            player program.
  254.  
  255.         6. The file 'NOTE' is the make file to build the NOTE
  256.            player program.
  257.  
  258.         7. The file 'SETPREF' is the make file to build the user
  259.            preference adjustment program.
  260.  
  261.         8. The file 'VOLUME' is the make file to build the Volume
  262.            control test program.
  263.  
  264.  
  265.     DRIVER DISKETTE CONTENTS:
  266.  
  267.         Disk Contents:
  268.  
  269.         REV.DOC         Revision changes for the SDK/DDK
  270.  
  271.         SDK.DOC         Intro documentation to the SDK
  272.         SDK.BAT         Batch file to build the release floppy
  273.         MKSDK.BAT       Batch file to build the example programs
  274.  
  275.         PASWAVE.COM     Pro Audio Spectrum WAVE VBE/AI driver
  276.         SSWAVE.COM      Disney Sound source WAVE VBE/AI driver
  277.         SBWAVE.COM      Sound Blaster & Compatibles WAVE VBE/AI driver
  278.         OPL2.COM        OPL2 VBE/AI MIDI driver
  279.         MPU.COM         MPU-401 VBE/AI MIDI driver
  280.  
  281.         ALFRE.MID       Sample MIDI file
  282.         GUPPY.WAV       Sample WAVE file
  283.  
  284.         OPL2.BNK        Instrument bank for the OPL2 MIDI driver
  285.         MT32            Patch map from GM to an MT32
  286.  
  287.         PLAY            Make file for the WAVE PLAY.EXE program
  288.         PLAY.C          Source to PLAY.EXE
  289.         PLAY.EXE        PLAY.EXE executable for playback testing of WAVE audio
  290.  
  291.         TESTW           Make file for the WAVE TESTW.EXE program
  292.         TESTW.C         Source to TESTW.EXE
  293.         TESTW.EXE       TESTW.EXE executable for playback testing of WAVE audio
  294.  
  295.         NOTE            Make file for the single MIDI note test program
  296.         NOTE.C          Source code for the single MIDI note test program
  297.         NOTE.EXE        Executable MIDI note test program
  298.  
  299.         PMIDI.C         Source to PMIDI.EXE midi file player
  300.         PMIDI           Make file for the MIDI PMIDI.EXE program
  301.         PMIDI.EXE       PMIDI.EXE executable for MIDI playback
  302.         PDATA.C         Static data for PMIDI.C
  303.  
  304.         SETPREF         Make file for setting user preferences & general query
  305.         SETPREF.C       Source to SETPREF.EXE executable
  306.         SETPREF.EXE     SETPREF.EXE executable to set user preference levels
  307.  
  308.         VOLUME          Make file for the volume test program
  309.         VOLUME.C        Tests the Volume control of a given device
  310.         VOLUME.EXE      Executable volume test program
  311.  
  312.         VESA.C          Mid level helper code for VBE/AI driver support
  313.  
  314.         MIDI.H          Miscellaneous header files
  315.         VBEAI.H
  316.         VESA.H
  317.         MIDI.INC
  318.         VBEAI.INC
  319.         WAVE.INC
  320.  
  321.         MIDI\OPL2\TOOLS A directory with s/w for building the OPL2.BNK and
  322.                         MT32 patch map.
  323.  
  324.