           Ŀ
                    Developer Kit For Sound Blaster Series        
                               Second Edition                     
                                                                  
               Copyright (c) Creative Technology Ltd, 1993-1996.  
                             All Rights Reserved.                 
                                                                  
           

    CONTENT
    =======
    1) Introduction
    2) Files in this package
    3) How to obtain the latest drivers
    4) Errata

   ----------------------------------------------------------------------
    Ŀ
    1) Introduction         
    

    The "Developer Kit for Sound Blaster Series, 2nd Edition (for DOS)"(SBK2)
    is designed for DOS developers who would like to develop software that
    exploit the features of Creative's line of Sound Blaster audio cards.

    The SBK2 supports:
        - SB AWE32
        - SB16
        - SB Pro
        - SB

    Note: SB AWE32 and SB32, both legacy or PnP version are collectively
          called SB AWE32. Similarly, SB16, with or without Advanced Signal
          Processor, legacy or PnP, are collectively known as SB16 etc.

    Developer who would like to utilize wavetable features of SB AWE32
    can download the AWE32 Developer Information Pack (AWEDIP) from
    Creative's FTP/Compuserve/BBS site. The SBK2 covers the common
    programming aspect aspects of SB family cards, such as digitized sound
    I/O, MIDI Port I/O, mixer chip etc. The AWEDIP is supplement to the
    SBK2. It covers only features specific to SB AWE32, such as the
    wavetable synthesis, 3D Positional Audio, SoundFont(R) downloading etc.

    SBK2 supports the following programming languages:

    - Microsoft Assembler version 4.0 or later
    - Microsoft C version 6.0 and 7.0
    - Microsoft Visual C++ version 1.0, 1.5
    - Turbo C version 2.0
    - Turbo C++ version 1.0
    - Borland C++ version 2.0, 3.0 and 3.1, 4.0
    - Microsoft Quick Basic version 4.5
    - Microsoft Basic Professional Development System version 7.1
    - Microsoft Visual Basic for DOS version 1.0
    - Turbo Pascal version 6.0 and 7.0

   Please note that this package is provided on "AS IS" basis. That means
   it is given to you free of charge, without warranty and support of any
   kind, express or implied. 

   ----------------------------------------------------------------------

    Ŀ
    2) Files In This Package    
    


   After the installation, the following files will reside in the target
   drive :-

   \SBK2 directory,

       README.TXT          - This file.

   \SBK2\DOC  directory

   contains documentations in Microsoft Word6 format

      PGMNL.DOC           - Programmer's Guide Manual
      LRMNL.DOC           - Library Reference Manul
      HWMNL.DOC           - Hardware Programming Reference

      Note : You can print certain page(s) of the document by using
             Print | Pages from Word's menu and specify the range
             of pages you want to print. For example,

             p1s2       will print out Page 1 of Section 2
             p1s2-p4s2  will print from Page 1 to Page 4 of Section 2


   \SBK2\INCLUDE directory

    To distinguish different types of programming languages, the
    character '?' is used to denote 'H', 'BI' and 'INC' for C
    language, Basic and PASCAL respectively.

    CTSTDDEF.H          - General C language macros, constants and
                          type definitions.

    CTMMLL.H            - Header file for CTMMSYS.SYS driver interface.
    CTMMSYS.H           - Header file for CTMMSYS.SYS driver interface.

    SBKAUX.?            - Header file for AUXDRV.DRV driver interface.
    SBKCD.?             - Header file for SBCD.SYS driver interface.
    SBKMIDI.?           - Header file for CTMIDI.DRV driver interface.
    SBKTS.?             - Header file for CTTS.DRV driver interface.
    SBKVOICE.?          - Header file for CT-VOICE.DRV and CTVDSK.DRV
                          drivers interface.
    SBKWAVE.?           - Header file for CTWMEM.DRV and CTWDSK.DRV
                          drivers interface.
    SBKMACRO.H          - Macros for Microsoft C, Turbo C and
                          Borland C compilers.

    SBKX.?              - Header file for helper functions.

    LOADDRV.C           - General function to load a loadable driver
                          into memory.


  \SBK2\LIB directory

    BASIC version libraries :-

    SBKBC7.LIB          - MS Basic PDS version 7.1 library.
    SBKBC7.QLB          - MS Basic PDS version 7.1 Quick library.
    BC7SBKX.LIB         - MS Basic PDS version 7.1 helper library.
    SBKQB45.LIB         - MS Quick Basic version 4.5 library.
    SBKQB45.QLB         - MS Quick Basic version 4.5 Quick library.
    QBSBKX.LIB          - MS Quick Basic version 4.5 helper library.
    SBKVB.LIB           - MS Visual Basic (DOS) version 1.0 library.
    SBKVB.QLB           - MS Visual Basic (DOS) version 1.0 Quick library.
    VBSBKX.LIB          - MS Visual Basic (DOS) version 1.0 helper library.

    C language version libraries :-

    SBKLIBS.LIB         - Small memory model library.
    SBKLIBC.LIB         - Compact memory model library.
    SBKLIBM.LIB         - Medium memory model library.
    SBKLIBL.LIB         - Large memory model library.
    CSBKX.LIB           - Memory model independent helper library.

    PASCAL version units :-

    SBKTP6.TPU          - Turbo Pascal version 6.0 unit.
    TP6SBKX.TPU         - Turbo Pascal version 6.0 helper unit.
    SBKTP7.TPU          - Turbo Pascal version 7.0 unit.
    TP7SBKX.TPU         - Turbo Pascal version 7.0 helper unit.


   \SBK2\HELPER directory

    ADDXADJ.ASM         -
    BSTRING.ASM         -
    CVTTYPE.ASM         -  Source for helper functions.
    CTMMSYS.ASM         -
    DOSRW.ASM           -  For detail information, read the header
    FILEIO.ASM          -  of each individual file.
    MEMORY.ASM          -
    XMSRTN.ASM          -
    SBKMODEL.INC        -

    SBKHELP.TXT         - Describes SBK helper functions in detailed.

    \BASIC sub-directory

    MSBKX.BAS           - BASIC helper source for MS PDS
                          version 7.1 and MS Visual Basic (DOS)
                          version 1.0
    QSBKX.BAS           - BASIC helper source for MS Quick
                          Basic version 4.5.
    MKBHLP.MK           - BASIC libraries make file.
    BHLP.BAT            - Batch file to build BASIC libraries.

    \CLANG sub-directory

    MKCHLP.MK           - C libraries make file.
    CHLP.BAT            - Batch file to build C libraries.

    \PASCAL sub-directory

    SBKX.PAS            - PASCAL helper source.
    MKPHLP.MK           - PASCAL units make file.
    PHLP.BAT            - Batch file to build PASCAL units.


  \SBK2\EXAMPLES directory

    The character '?' is used to denote 'BAS', 'C' and 'PAS' for
    BASIC, C and PASCAL respectively. In below "xxxx" can be "BASIC"
    "CLANG" or "PASCAL. It depends on the type of language version
    installed.

    \xxxx\CDROM sub-directory

    DEMOCD.?            - Sample program to play Compact Disc player.
    DEMOCD.MAK          - Make file for Borland C and Turbo C
                          compiler.

    \xxxx\GENERAL sub-directory

    SBKBLST.?           - Sample program to interpret BLASTER
                          environment settings.
    SBKVER.?            - Program to check SBK library's version.

    \xxxx\MIDI sub-directory

    DEMOMIDI.?          - Sample program to play MIDI files.
    DEMOMIDI.MAK        - Make file for Borland C and Turbo C
                          compiler.
    MIDIIN.?            - Sample program to perform MIDI input (record)
                          with time-stamped.
    MIDIIN.MAK          - Make file for Borland C and Turbo C
                          compiler.
    MIDIOUT.?           - Sample program to perform MIDI output
                          note by note.
    MIDIOUT.MAK         - Make file for Borland C and Turbo C
                          compiler.

    \xxxx\MIXER sub-directory

    DEMOMIX.?           - Sample program to control Creative Mixer chip.
                          Set volume, tone etc.
    DEMOMIX.MAK         - Make file for Borland C and Turbo C
                          compiler.
    DEMOFADE.?          - Sample program to demonstrate fading effect.
    DEMOFADE.MAK        - Make file for Borland C and Turbo C
                          compiler.
    DEMOPAN.?           - Sample program to demonstrate panning effect.
    DEMOPAN.MAK         - Make file for Borland C and Turbo C
                          compiler.


    \xxxx\VOICE sub-directory

    DEMOVMR.?           - Sample program to record Voice direct
                          to conventional memory.
    DEMOVMR.MAK         - Make file for Borland C and Turbo C
                          compiler.
    DEMOVXP.?           - Sample program to play Voice direct
                          from extended memory.
    DEMOVXP.MAK         - Make file for Borland C and Turbo C
                          compiler.
    DEMOVXR.?           - Sample program to record Voice direct
                          to extended memory.
    DEMOVXR.MAK         - Make file for Borland C and Turbo C
                          compiler.
    DEMOWDP.?           - Sample program to play a Wave file direct
                          from disk.
    DEMOWDP.MAK         - Make file for Borland C and Turbo C
                          compiler.
    DEMOWDR.?           - Sample program to record a compressed/
                          uncompressed Wave file direct to disk.
    DEMOWDR.MAK         - Make file for Borland C and Turbo C
                          compiler.
    DEMOWMP.?           - Sample program to play Wave direct
                          from memory.
    DEMOWMP.MAK         - Make file for Borland C and Turbo C
                          compiler.
    VOCWALK.?           - Sample program to interpret Creative
                          Voice File Format.
    VOCWALK.MAK         - Make file for Borland C and Turbo C
                          compiler.

\SBK\EXAMPLES\LOWLEVEL directory

    \MIDI\ sub-directory

    CTMIDILL.ASM        - Sample program to demonstrate direct
                          hardware programming for MIDI operation.

    \VOICE\ sub-directory
    These two programs access CTMMSYS.SYS directly.

    CTMMPLAY.C          - Sample program to play raw digitized data
                          direct from disk.
    CTMMPLAY.MAK        - Make file for Borland C and Turbo C
                          compiler.
    CTMMREC.C           - Sample program to record raw digitized data
                          direct to disk.
    CTMMREC.MAK         - Make file for Borland C and Turbo C
                          compiler.


\SBK\VOCUTIL directory

   Update version of digitized sound playback and recording utils.

   VPLAY.EXE            - Creative Voice playback util.
   VREC.EXE             - Creative Voice recording util.
   WPLAY.EXE            - Microsoft Wave playback util.
   WREC.EXE             - Microsoft Wave recording util.


Ŀ
 Important information about the Code Examples and Drivers           

a. Code examples are provided to show you the basic steps to program
   the Sound Blaster family of cards. If you find the sub-functions in
   the examples useful, feel free to extract and use these functions.

b. Please note that the code examples assume that the memory allocated
   will be freed by DOS upon their termination.

c. Before you compile and execute the code examples, please read
   through the header of each individual file to get a detailed
   description of each program.

d. If you are executing the code under Quick Basic or Microsoft Basic
   PDS environment, you may get an error message indicating
   insufficient memory space. This is because the code examples
   requires a large memory buffer for the I/O process.


Ŀ
 3. How to get the latest drivers                                    


 You can download the lastest drivers from Creative's FTP site,
 CompuServe Forum or BBS.

 FTP Site   : ftp.creaf.com
 WEB        : www.creaf.com
 CompuServe : GO BLASTER

Ŀ
 4. ERRATA                                                           


Please take note of the following printing errors in the Library
Reference manual.

a.  On page 1-8

    GetEnvSettings

    // Under section "Return Value", an addition error code is added:
    // This only applies to drivers
    //      Ctvdsk.drv version      4.06 onwards
    //      Ctwdsk.drv version      4.04 onwards
    //      Ct-voice.drv version    4.05 onwards
    //      Ctwmem.drv version      4.02 onwards

    Value       Meaning
   
    0x0020      Low level driver error.


b.  On page 2-2

    Chapter 2
    High-Level Auxiliary Driver

    // Three additional functions have been added into the Auxiliary
    // Driver (AUXDRV.DRV) version 4.10 and above. From this version
    // onward, the AUXDRV does not require Creative Multimedia System
    // Driver (CTMMSYS.SYS) and Creative Hardware Dependent Sound
    // Driver (CTSB16.SYS, CTSBPRO.SYS, CTSB2.SYS or CTSB.SYS) in order
    // to work. But it is hardware dependent driver.

    // The following describes the high-level language interface for C,
    // Basic and Pascal.

    1.          ctadSetFilter

    Action      Set the mixer's input/output filter.

    Syntax      C       WORD ctadSetFilter( WORD wFilter, WORD wMode )
                Pascal  ctadSetFilter( wFilter, wMode: WORD ) : WORD
                Basic   ctadSetFilter%( wFilter%, wMode% )

    Parameters  wFilter
                    0   - Input filter.
                    1   - Output filter.
                wMode
                    Input filter :-
                        0   - Low filter.
                        1   - High filter.
                        2   - Turn off filter.
                    Output filter :-
                        0   - Turn off filter.
                        1   - Turn on filter.

    Return Value    Return zero if successful else return non-zero.

    2.          ctadGetFilter

    Action      Get the mixer's input/output filter setting.

    Syntax      C       WORD ctadGetFilter( WORD wFilter )
                Pascal  ctadGetFilter( wFilter: WORD ) : WORD
                Basic   ctadGetFilter%( wFilter% )

    Parameters  wFilter
                    0   - Input filter.
                    1   - Output filter.

    Return Value    Return value as described in the following if
                    successfull else return -1.

                    Input filter :-
                        0   - Low filter.
                        1   - High filter.
                        2   - Filter is off.
                    Output filter :-
                        0   - Filter is off.
                        1   - Filter is on.


    3.          ctadQueryMixerCaps

    Action      Queries the mixer's capabilities, the sources supported
                and whether it provides tone or filter controls and etc.

    Syntax      C       DWORD ctadQueryMixerCaps( WORD wSubFunction )
                Pascal  ctadQueryMixerCaps( wSubFunction: WORD ) : longint
                Basic   ctadQueryMixerCaps&( wSubfunction% )

    Parameters  wSubFunction
                    Specifies the mixer's subfunction.

   
    Constant        Meaning
   
    QUERY_ADDINFO   Additional information about the mixer.
    QUERY_LRECSRC   Left recording source switches.
    QUERY_RRECSRC   Right recording source switches.
    QUERY_LMUTE     Left mute switches.
    QUERY_RMUTE     Right mute switches.
    QUERY_VOLSRC    Volume source.
    QUERY_TONECTRL  Tone control.
    QUERY_GAINCTRL  Gain control.
    QUERY_AGC       AGC control.
    QUERY_FILTER    Filter control.

    Return Value    The high and low word hold the mode (Left/Right
                    control), and the supported features in bit-oriented
                    combination for all subfunction, except QUERY_ADDINFO.

                    One should query the QUERY_ADDINFO before other
                    subfunctions. The QUERY_ADDINFO subfunction will return
                    information about whether the mixer support multiple
                    recording source, and whether there are separate left
                    and right channel recording or mute switches.

    QUERY_ADDINFO :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 0 0    Not Applicable
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 1 1    Additional info

                Bit 0  - Multiple sources
                Bit 1  - Recording switches
                Bit 2  - Mute switches

    Note: Bit 0 set (1) denotes the mixer supports multiple recording
          sources, it will be cleared (0) otherwise.

          Bit 1 set denotes the mixer has a separate Left/Right channel
          recording switches.

          If there are separate Left/Right recording switches control,
          one may query for the supported sources for each channel through
          QUERY_LRECSRC and QUERY_RRECSRC. Otherwise, only QUERY_RRECSRC
          is recognised.

          Bit 2 set denotes the mixer does not provide a separate Left/Right
          channel mute switches.

          If there is no separate Left/Right mute switches control, one may
          only query for the supported mute switches through QUERY_RMUTE.

    QUERY_LRECSRC :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 1 1 1 0    Left/Right control
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 1 1 1 1    Recording switches

                Bit 0  - Mic
                Bit 1  - CD
                Bit 2  - Line-In
                Bit 3  - FM

    QUERY_RRECSRC :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 1 1 1 0    Left/Right control
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 1 1 1 1    Recording switches

                Bit 0  - Mic
                Bit 1  - CD
                Bit 2  - Line-In
                Bit 3  - FM

    QUERY_LMUTE :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 0 0    Not Applicable
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 0 0    Not Applicable

    Note: If the return value is zero, it indicates that the QUERY_LMUTE
          is not recognised. Hence, one should control the mute switches
          through QUERY_RMUTE only.

    QUERY_RMUTE :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 0 1 1 0    Left/Right control
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 0 1 1 1    Mute switches

                Bit 0  - Mic
                Bit 1  - CD
                Bit 2  - Line-In

    QUERY_VOLSRC :-

                MSB                          LSB
    HIGH WORD : 1 0 1 0 0 0 0 0  0 0 0 0 1 1 1 0    Left/Right control
    LOW WORD  : 1 1 1 0 0 0 0 0  0 0 0 0 1 1 1 1    Volume sources

                Bit 0  - Mic
                Bit 1  - CD
                Bit 2  - Line-In
                Bit 3  - FM
                Bit 13 - Voice
                Bit 14 - PC-Speaker
                Bit 15 - Master

    QUERY_TONECTRL :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 1 1    Left/Right control
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 1 1    Tone control

                Bit 0  - Treble
                Bit 1  - Bass

    QUERY_GAINCTRL :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 1 1    Left/Right control
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 1 1    Gain control

                Bit 0  - Input gain
                Bit 1  - Output gain

    QUERY_AGC :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 0 0    Not Applicable
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 0 1    AGC

                Bit 0  - Mic

    QUERY_FILTER :-

                MSB                          LSB
    HIGH WORD : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 0 0    Not Applicable
    LOW WORD  : 0 0 0 0 0 0 0 0  0 0 0 0 0 0 1 1    Filter cntrol

                Bit 1  - Input filter
                Bit 2  - Output filter

    Remarks     Setting of 1 denotes supported feature, or separate
                Left/Right channel control is available.

                All bits not used are set to 0, and they are reserved
                for future expansion.

                Calling ctadQueryMixerCaps function with unrecognised
                subfunction will receive return value of -1.

    IMPORTANT   ctadQueryMixerCaps function is supported in Auxiliary
                driver version 4.10 abd above only. Application should
                check that the return value is not -1 before processing
                the return value.

    // The following describes the Assembly Interface

    1.          30  Set Filter

    Action      Set the mixer's input/output filter.

    Entry       BX = 30
                AX = wFilter (see above High-Level interface)
                DX = wMode   (see above High-Level interface)

    Exit        AX = zero if successful else non-zero.

    2.          31  Get Filter

    Action      Get the mixer's input/output filter setting.

    Entry       BX = 31
                AX = wFilter

    Exit        AX = (see above High-Level interface).

    3.          32  Query Mixer Capabilities

    Action      Queries the mixer's capabilities, the sources supported
                and whether it provides tone or filter controls and etc.

    Entry       BX = 32
                AX = wSubFunction (see above High-Level interface)

    Exit        DX:AX (see above High-Level interface)


c.  On page 3-7

    // The message CSPDM_STATE_Query is missing.
    // The following source has been added to
    // CTMMSYS.H file under the \INCLUDE directory:

    /*** For CSPDM_STATE_Query
     *
     *      Invocation
     *      ----------
     *      CSPSTATE    CspState;                                                         ---  THE END ---
     *
     *      MmSysProc(hDev, MMDEVICE_CSP, CSPDM_STATE_Query,
     *                (DWORD)(LPCSPSTATE)&CspState, PARAM_UNUSED);
     *
     *      Return value
     *      ------------
     *      MMSTATUS_SUCCESS
     *      MMSTATUS_BAD_HANDLE
     */
    typedef DWORD   CSPSTATE;
    typedef CSPSTATE FAR  *LPCSPSTATE;

    #define CSPSTATE_INACTIVE   0
    #define CSPSTATE_STANDBY    1
    #define CSPSTATE_ACTIVE     2


d.  On page 4-6

    ctmdGetEnvSettings

    // Under section "Remarks", the following addition notes are added:

    NOTE: The driver only analyses the syntax of the BLASTER environment
    string and will not responsible for ensuring the physical hardware
    setting is set correctly. No default settings will be assumed in this
    case, application needs to quit if the call is failed.

    // Under section "Return Value", the error messages have been changed
    // as following:

    Return Value    Zero if successful or else a word with following
                    bit(s) set to indicate error:

                           Bit 0  - unrecognised Base I/O Address
                           Bit 1  - unrecognised IRQ
                           Bit 2  - unrecognised MPU-401 Base I/O
                                    Address
                           Bit 15 - calling sequence error


e.  On page 4-8

    ctmdGetMidiEnvSettings

    // Under section "Remarks" the following note is added:

    NOTE: If the call is failed, application can still proceed, driver
    will use the default value.

    // Under section "Return Value" the errror messages have been changed
    // as following:

    Return Value    Zero if successful or else a word with the following
                    bit(s) set to indicate error:

                           Bit 0  - unrecognised SYNTH:option
                           Bit 1  - unrecognised MAP:option
                           Bit 15 - calling sequence error


f.  On page 5-11

    // DISK_INFO should be DISC_INFO
    // DISKxINFO should be DISCxINFO

    sbcdGetDiscInfo(DISK_INFO far *lpBuffer)
    sbcdGetDiscInfo(var lpBuffer: DISK_INFO): integer
    sbcdGetDiscInfo%(SEG lpBuffer AS DISKxINFO)

                            -- THE END --
