home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 24 / CD_ASCQ_24_0995.iso / dos / prg / dsik205 / dsik.dat / GUIDE.TXT < prev    next >
Text File  |  1995-04-10  |  49KB  |  1,309 lines
  1. -----------------------------------------------------------------------------
  2.                      Digital Sound Interface Kit (DSIK)
  3.                                 Version 2.00
  4.  
  5.                             -- Reference Guide --
  6.  
  7.          Copyright (c) 1993-95 by Carlos Hasan. All Rights Reserved.
  8. -----------------------------------------------------------------------------
  9.  
  10. This file provides information about all the procedures and functions used
  11. to work with the sound system.
  12.  
  13.  
  14. 1. Procedures and Functions:
  15.  
  16. dAutoDetect
  17. -----------------------------------------------------------------------------
  18. Function:       Soundcard autodetection routine.
  19.  
  20. Prototype:      int dAutoDetect(SoundCard *SC)
  21.  
  22. Parameters:     SC  - soundcard structure
  23.  
  24. Returns:        Return zero on success.
  25.  
  26. Description:    This routine will try to detect a soundcard. It uses safe
  27.                 detection routines based on environment variables and
  28.                 system calls to soundcard drivers.
  29.                 This routine can't detect all the supported soundcards,
  30.                 so is highly recommended to use the SETUP.EXE utility and
  31.                 the dLoadSetup routine to get the soundcard parameters.
  32.  
  33. See Also:       dLoadSetup, dInit.
  34.  
  35.  
  36. dDone
  37. -----------------------------------------------------------------------------
  38. Function:       Deinitializes the sound system.
  39.  
  40. Prototype:      int dDone(void)
  41.  
  42. Parameters:     None.
  43.  
  44. Returns:        Returns zero on success.
  45.  
  46. Description:    This routine will deinitialize the sound system, must be
  47.                 called before leaving from your program.
  48.  
  49. See Also:       dInit.
  50.  
  51.  
  52. dDoneTimer
  53. -----------------------------------------------------------------------------
  54. Function:       Deinitializes the timer services.
  55.  
  56. Prototype:      void dDoneTimer(void)
  57.  
  58. Parameters:     None.
  59.  
  60. Returns:        None.
  61.  
  62. Description:    Shutdown the timer services routines, must be called before
  63.                 exiting from your program.
  64.  
  65. See Also:       dInitTimer.
  66.  
  67.  
  68. dFreeModule
  69. -----------------------------------------------------------------------------
  70. Function:       Releases memory used by a module.
  71.  
  72. Prototype:      void dFreeModule(DSM *MusicPtr)
  73.  
  74. Parameters:     MusicPtr - module address
  75.  
  76. Returns:        None.
  77.  
  78. Description:    Routine used to release all the memory used by a module.
  79.                 You cannot call this function while the sound system is
  80.                 playing the module.
  81.  
  82. See Also:       dLoadModule.
  83.  
  84.  
  85. dFreeSample
  86. -----------------------------------------------------------------------------
  87. Function:       Releases memory used by a sample.
  88.  
  89. Prototype:      void dFreeSample(Sample *SampPtr)
  90.  
  91. Parameters:     SampPtr     - sample structure
  92.  
  93. Returns:        None.
  94.  
  95. Description:    Used to release the memory used by a sample. You cannot
  96.                 release a sample while it's being played by the system.
  97.  
  98. See Also:       dLoadSample, dImportSample.
  99.  
  100.  
  101. dGetDriverFlags
  102. -----------------------------------------------------------------------------
  103. Function:       Returns the current driver capabilities bit flags.
  104.  
  105. Prototype:      int dGetDriverFlags(void)
  106.  
  107. Parameters:     None.
  108.  
  109. Returns:        Driver capabilities flags.
  110.  
  111. Description:    This routine returns the capabilities bit flags of the
  112.                 current active sound driver. The following constants are
  113.                 defined:
  114.  
  115.                 Constant    Value   Description
  116.                 -------------------------------------------------------
  117.                 AF_8BITS    0x00    8-bits per sample
  118.                 AF_16BITS   0x01    16-bits per sample
  119.                 AF_MONO     0x00    mono output mode
  120.                 AF_STEREO   0x02    stereo output mode
  121.                 AF_NODRAM   0x00    samples stored in system memory
  122.                 AF_DRAM     0x04    samples stored in soundcard memory
  123.  
  124.                 For example, if you want to know if the current driver
  125.                 is playing in 16-bit mode:
  126.  
  127.                         if (dGetDriverFlags() & AF_16BITS)
  128.                            printf("16-bit output mode.\n");
  129.  
  130.                 However, drivers that support 16-bit and/or stereo output
  131.                 mode can be forced to use 8-bit and/or mono output mode.
  132.                 This function will return the output mode currently used
  133.                 by the sound system.
  134.  
  135. See Also:       dInit, dDone.
  136.  
  137.  
  138. dGetDriverStruc
  139. -----------------------------------------------------------------------------
  140. Function:       Return the driver structure for a given driver identifier.
  141.  
  142. Prototype:      Driver *dGetDriverStruc(int DriverId)
  143.  
  144. Parameters:     DriverId    - driver identifier value
  145.  
  146. Returns:        Driver structure address or NULL if not found.
  147.  
  148. Description:    Returns the driver structure address for a specified driver
  149.                 identifier. The following driver identifiers are defined:
  150.  
  151.                 Constant        Description
  152.                 --------------------------------------
  153.                 ID_NONE         No sound
  154.                 ID_SB           Sound Blaster
  155.                 ID_SB201        Sound Blaster 2.01
  156.                 ID_SBPRO        Sound Blaster Pro
  157.                 ID_SB16         Sound Blaster 16
  158.                 ID_PAS          Pro Audio Spectrum
  159.                 ID_PASPLUS      Pro Audio Spectrum+
  160.                 ID_PAS16        Pro Audio Spectrum 16
  161.                 ID_WSS          Windows Sound System
  162.                 ID_GUS          Gravis UltraSound
  163.  
  164.                 It will return NULL if the driver does not exists. Note
  165.                 that the sound system only knows the drivers that were
  166.                 already registered using dRegisterDriver.
  167.  
  168. See Also:       dRegisterDriver, dRegisterDrivers.
  169.  
  170.  
  171. dGetMusicStatus
  172. -----------------------------------------------------------------------------
  173. Function:       Returns the music player status.
  174.  
  175. Prototype:      int dGetMusicStatus(void)
  176.  
  177. Parameters:     None.
  178.  
  179. Returns:        PS_PLAYING   - music is being played
  180.                 PS_STOPPED   - music is stopped
  181.                 PS_PAUSED    - music is paused
  182.  
  183. Description:    Returns the current state of the music player.
  184.  
  185. See Also:       dPlayMusic, dStopMusic, dPauseMusic, dResumeMusic.
  186.  
  187.  
  188. dGetMusicStruc
  189. -----------------------------------------------------------------------------
  190. Function:       Returns the internal music structure.
  191.  
  192. Prototype:      MHdr *dGetMusicStruc(void)
  193.  
  194. Parameters:     None.
  195.  
  196. Returns:        Music structure address.
  197.  
  198. Description:    Returns the address of an static structure used by the
  199.                 sound system to play the current music module. You can
  200.                 use this structure to synchronize your program with
  201.                 the music and/or sound effects.
  202.  
  203. Important:      If you are using the ID_NONE sound driver, the music player
  204.                 will be inactive and the music structure won't be updated.
  205.  
  206. See Also:       None.
  207.  
  208.  
  209. dGetVoicePos
  210. -----------------------------------------------------------------------------
  211. Function:       Return the voice's relative playing position.
  212.  
  213. Prototype:      long dGetVoicePos(int Voice)
  214.  
  215. Parameters:     Voice   - voice number (0-31)
  216.  
  217. Returns:        Relative playing position.
  218.  
  219. Description:    This function returns the playing position of the sample
  220.                 that is being played on the specified voice.
  221.                 For soundcards that do not use onboard memory to store
  222.                 samples, you can use this routine to implement your own
  223.                 double-buffering sound player (it is useful if you want
  224.                 to play huge sample files).
  225.  
  226. See Also:       dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceVolume,
  227.                 dSetVoiceBalance, dGetVoiceStatus.
  228.  
  229.  
  230. dGetVoiceStatus
  231. -----------------------------------------------------------------------------
  232. Function:       Return the current status of a specified voice.
  233.  
  234. Prototype:      int dGetVoiceStatus(int Voice)
  235.  
  236. Parameters:     Voice   - voice number (0-31)
  237.  
  238. Returns:        PS_PLAYING  - sample is being played
  239.                 PS_STOPPED  - sample is stopped
  240.  
  241. Description:    Return the status of the voice. Notice that voices playing
  242.                 looped samples will never stop. However, you can stop those
  243.                 voices using dStopVoice.
  244.  
  245. See Also:       dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceVolume,
  246.                 dSetVoiceBalance, dGetVoicePos.
  247.  
  248.  
  249. dImportModule
  250. -----------------------------------------------------------------------------
  251. Function:       Imports music module files.
  252.  
  253. Prototype:      DSM *dImportModule(char *Filename, int Form)
  254.  
  255. Parameters:     Filename    - full path of the music module
  256.                 Form        - music module format
  257.  
  258. Returns:        Music module structure address or NULL if error.
  259.  
  260. Description:    Used to import music modules. The following music module
  261.                 formats are supported:
  262.  
  263.                 Constant        Description
  264.                 -----------------------------------------------
  265.                 FORM_DSM        RIFF/DSMF module files
  266.                 FORM_MOD        Protracker/FastTracker modules
  267.                 FORM_S3M        Scream Tracker 3.0 modules
  268.                 FORM_MTM        Multitracker 1.0 modules
  269.                 FORM_669        Composer 669 modules
  270.                 FORM_STM        Scream Tracker 2.0 modules
  271.  
  272.                 If something went wrong, the function returns NULL and
  273.                 the global variable dError is set with the error type.
  274.  
  275.                 Is highly recommended to use dLoadModule and RIFF/DSMF
  276.                 module files in your programs. The M2DSM.EXE program used
  277.                 to convert other module formats will remove most of the
  278.                 problems that other formats may have.
  279.  
  280. See Also:       dLoadModule.
  281.  
  282.  
  283. dImportModuleFile
  284. -----------------------------------------------------------------------------
  285. Function:       Imports music module files.
  286.  
  287. Prototype:      DSM *dImportModuleFile(int Handle, long Length, int Form)
  288.  
  289. Parameters:     Handle      - DOS file handle
  290.                 Length      - module file length
  291.                 Form        - module file format
  292.  
  293. Returns:        Music module structure address or NULL if error.
  294.  
  295. Description:    Used to import music modules. It is near equivalent to
  296.                 dImportModule but it uses a DOS file handle to load the
  297.                 module file. Useful when module files are stored into
  298.                 a single resource file.
  299.  
  300. See Also:       dLoadModule, dImportModule.
  301.  
  302.  
  303. dImportSample
  304. -----------------------------------------------------------------------------
  305. Function:       Imports sample files.
  306.  
  307. Prototype:      Sample *dImportSample(char *Filename, int Form)
  308.  
  309. Parameters:     Filename    - full path of the sample file
  310.                 Form        - sample file format
  311.  
  312. Returns:        Sample structure address or NULL if error.
  313.  
  314. Description:    Used to import sample files. The format parameter specifies
  315.                 the sample file format:
  316.  
  317.                 Constant        Description
  318.                 -------------------------------------------------
  319.                 FORM_WAV        Microsoft RIFF/WAVE sample files
  320.                 FORM_VOC        Creative Labs VOICE sample files
  321.                 FORM_IFF        Amiga IFF/8SVX sample files
  322.                 FORM_RAW        8-bit signed RAW sample files
  323.  
  324.                 If something went wrong, the function returns NULL and
  325.                 the global variable dError is set with the error type.
  326.  
  327. See Also:       dLoadSample.
  328.  
  329.  
  330. dImportSampleFile
  331. -----------------------------------------------------------------------------
  332. Function:       Imports sample files.
  333.  
  334. Prototype:      Sample *dImportSampleFile(int Handle, long Length, int Form)
  335.  
  336. Parameters:     Handle      - DOS file handle
  337.                 Length      - sample file length
  338.                 Form        - sample file format
  339.  
  340. Returns:        Sample structure address or NULL if error.
  341.  
  342. Description:    Used to import sample files. It is near equivalent to
  343.                 dImportSsample but it uses a DOS file handle to load the
  344.                 sample file. Useful when sample files are stored into
  345.                 a single resource file.
  346.  
  347. See Also:       dLoadSample, dImportSample.
  348.  
  349.  
  350. dInit
  351. -----------------------------------------------------------------------------
  352. Function:       Initializes the sound system.
  353.  
  354. Prototype:      int dInit(SoundCard *SC)
  355.  
  356. Parameters:     SC  - soundcard structure
  357.  
  358. Returns:        Returns zero on success.
  359.  
  360. Description:    Initializes the sound system using the soundcard's hardware
  361.                 parameters specified in the structure. You must call dDone
  362.                 before exiting from your program to deinitialize the sound
  363.                 system.
  364.  
  365. See Also:       dDone, dRegisterDrivers.
  366.  
  367.  
  368. dInitTimer
  369. -----------------------------------------------------------------------------
  370. Function:       Initializes the timer services.
  371.  
  372. Prototype:      void dInitTimer(void)
  373.  
  374. Parameters:     None.
  375.  
  376. Returns:        None.
  377.  
  378. Description:    Initializes the timer interrupt services. You must call
  379.                 the dDoneTimer to deinitialize the timer services before
  380.                 leaving from your program.
  381.  
  382. See Also:       dDoneTimer.
  383.  
  384.  
  385. dLoadDriver
  386. -----------------------------------------------------------------------------
  387. Function:       Load a dynamic-link audio driver from disk.
  388.  
  389. Prototype:      Driver *dLoadDriver(SoundCard *SC)
  390.  
  391. Parameters:     SC          - soundcard structure
  392.  
  393. Returns:        Audio driver address or NULL if error.
  394.  
  395. Description:    This routine is used to load dynamic-link audio drivers
  396.                 from disk. You must use dRegisterDriver to register the
  397.                 dynamic-link audio driver.
  398.                 You should not reference any of the static-link drivers
  399.                 in your programs, and you shouldn't use dRegisterDrivers
  400.                 to install the static-link audio drivers.
  401.                 Here is an example to initialize the sound system using
  402.                 dynamic-link audio drivers:
  403.  
  404.                 dLoadSetup(&SC,"SETUP.CFG");
  405.                 dRegisterDriver(dLoadDriver(&SC));
  406.                 dInit(&SC);
  407.  
  408.                 the above lines will initialize the sound system. You
  409.                 can use the MKDRV.BAT batch file to build the audio
  410.                 driver files (ie. SB.DRV, PAS.DRV, WSS.DRV, etc).
  411.  
  412. See Also:       dRegisterDriver, dRegisterDrivers.
  413.  
  414.  
  415. dLoadModule
  416. -----------------------------------------------------------------------------
  417. Function:       Load a RIFF/DSMF music module file.
  418.  
  419. Prototype:      DSM *dLoadModule(char *Filename)
  420.  
  421. Parameters:     Filename    - full path of the music module
  422.  
  423. Returns:        Module structure address of NULL if error.
  424.  
  425. Description:    Used to load RIFF/DSMF modules. If an error occurs while
  426.                 loading the module, this function will return NULL and the
  427.                 global variable dError will be set to one of the following
  428.                 error values:
  429.  
  430.                 Constant        Description
  431.                 ----------------------------------------------
  432.                 ERR_FORMAT      Invalid file format
  433.                 ERR_NOFILE      File does not exist
  434.                 ERR_FILEIO      Error reading the module file
  435.                 ERR_NOMEM       Not enough system memory
  436.                 ERR_NODRAM      Not enough soundcard memory
  437.  
  438.                 You can use the M2DSM.EXE program to convert other module
  439.                 formats to RIFF/DSMF music module files. Also, you can
  440.                 convert other modules formats from your programs, using
  441.                 the built-in import routines.
  442.                 If your program needs to use a lot of samples, you can
  443.                 pack all those samples into a big module file. You will
  444.                 need a tracker/composer to do it.
  445.  
  446. See Also:       dFreeModule, dImportModule, dLoadModuleFile.
  447.  
  448.  
  449. dLoadModuleFile
  450. -----------------------------------------------------------------------------
  451. Function:       Load a RIFF/DSMF music module file.
  452.  
  453. Prototype:      DSM *dLoadModuleFile(int Handle, dword Length)
  454.  
  455. Parameters:     Handle      - DOS file handle
  456.                 Length      - module file length
  457.  
  458. Returns:        Module structure address of NULL if error.
  459.  
  460. Description:    Used to load RIFF/DSMF modules. It is near equivalent
  461.                 to the dLoadModule routine. It is useful to load music
  462.                 modules from your own resource data files.
  463.  
  464. See Also:       dFreeModule, dImportModule, dLoadModule.
  465.  
  466.  
  467. dLoadSample
  468. -----------------------------------------------------------------------------
  469. Function:       Load RIFF/WAVE sample files.
  470.  
  471. Prototype:      Sample *dLoadSample(char *Filename)
  472.  
  473. Parameters:     Filename    - full path of sample file
  474.  
  475. Returns:        Sample structure address or NULL if error.
  476.  
  477. Description:    This function load RIFF/WAVE sample files. You can use
  478.                 import routines to load other formatted sample files.
  479.                 If something went wrong, the function returns NULL and
  480.                 the global variable dError is set with the error type.
  481.  
  482. See Also:       dFreeSample, dImportSample, dLoadSampleFile.
  483.  
  484.  
  485. dLoadSampleFile
  486. -----------------------------------------------------------------------------
  487. Function:       Load RIFF/WAVE sample files.
  488.  
  489. Prototype:      Sample *dLoadSampleFile(int Handle, dword Length)
  490.  
  491. Parameters:     Handle      - DOS file handle
  492.                 Length      - sample file length
  493.  
  494. Returns:        Sample structure address or NULL if error.
  495.  
  496. Description:    Routine used to load RIFF/WAVE samples. It is similar
  497.                 to the dLoadSample routine. It is useful to load samples
  498.                 from your own resource data files.
  499.  
  500. See Also:       dFreeSample, dImportSample, dLoadSample.
  501.  
  502.  
  503. dMemAlloc
  504. -----------------------------------------------------------------------------
  505. Function:       Allocates and uploads samples to the soundcard memory.
  506.  
  507. Prototype:      long dMemAlloc(Sample *SampPtr)
  508.  
  509. Parameters:     SampPtr - sample structure address
  510.  
  511. Returns:        Sample address in the soundcard memory or NULL if error.
  512.  
  513. Description:    This routine allocates and upload samples to the soundcard
  514.                 memory (when applicable). You should not use this routine
  515.                 directly from your programs.
  516.  
  517. See Also:       dMemFree, dMemAvail.
  518.  
  519.  
  520. dMemAvail
  521. -----------------------------------------------------------------------------
  522. Function:       Returns the amount of free memory in the soundcard.
  523.  
  524. Prototype:      long dMemAvail(void)
  525.  
  526. Parameters:     None.
  527.  
  528. Returns:        Amount of free memory or zero if the soundcard does
  529.                 not have onboard memory.
  530.  
  531. Description:    Return the amount of free soundcard memory. You may use
  532.                 this routine to verify if the user has enough memory on
  533.                 his soundcard to upload your samples.
  534.  
  535. See Also:       dMemAlloc, dMemFree.
  536.  
  537.  
  538. dMemFree
  539. -----------------------------------------------------------------------------
  540. Function:       Releases memory allocated by dMemAlloc.
  541.  
  542. Prototype:      void dMemFree(Sample *SampPtr)
  543.  
  544. Parameters:     SampPtr - sample structure address
  545.  
  546. Returns:        None.
  547.  
  548. Description:    Used internally to release a block of memory allocated
  549.                 in the soundcard memory (when applicable). You should
  550.                 not use this routine directly from your programs.
  551.  
  552. See Also:       dMemAlloc, dMemAvail, dLoadSample, dFreeSample.
  553.  
  554.  
  555. dPauseMusic
  556. -----------------------------------------------------------------------------
  557. Function:       Pauses the current music module.
  558.  
  559. Prototype:      int dPauseMusic(void)
  560.  
  561. Parameters:     None.
  562.  
  563. Returns:        Return zero on success.
  564.  
  565. Description:    Pauses the current music module. You must call dResumeMusic
  566.                 to continue playing the current module.
  567.  
  568. See Also:       dStopMusic, dResumeMusic.
  569.  
  570.  
  571. dPlayMusic
  572. -----------------------------------------------------------------------------
  573. Function:       Start playing a music module.
  574.  
  575. Prototype:      int dPlayMusic(DSM *MusicPtr)
  576.  
  577. Parameters:     MusicPtr    - module structure address
  578.  
  579. Returns:        Return zero on success.
  580.  
  581. Description:    This routine will start playing a music module. You must
  582.                 have enough active voices to play the music module.
  583.                 You can use the dPlayPatterns routine to play sequences
  584.                 or chunks of the music module.
  585.  
  586. See Also:       dStopMusic, dPauseMusic, dResumeMusic, dSetupVoices.
  587.  
  588.  
  589. dPlayPatterns
  590. -----------------------------------------------------------------------------
  591. Function:       Start playing a sequence of music patterns.
  592.  
  593. Prototype:      int dPlayPatterns(DSM *MusicPtr, int OrderPos, int OrderEnd)
  594.  
  595. Parameters:     MusicPtr    - module structure address
  596.                 OrderPos    - starting order position (0-127)
  597.                 OrderEnd    - ending order position (0-127)
  598.  
  599. Returns:        Return zero on success.
  600.  
  601. Description:    This routine will start playing a sequence of patterns. You
  602.                 must specify the starting and ending positions of the order
  603.                 list to be played.
  604.                 The order list is an array of pattern numbers used to play
  605.                 the music patterns in a specified order or sequence. You
  606.                 can play chunks of the song using this routine.
  607.                 For example, you can use a single module to save multiple
  608.                 sequences of music and/or sound effects.
  609.  
  610. See Also:       dStopMusic, dPauseMusic, dResumeMusic, dSetupVoices.
  611.  
  612.  
  613. dPlayVoice
  614. -----------------------------------------------------------------------------
  615. Function:       Start playing a sample.
  616.  
  617. Prototype:      void dPlayVoice(int Voice, Sample *SampPtr)
  618.  
  619. Parameters:     Voice   - voice number (0-31)
  620.                 SampPtr - sample structure
  621.  
  622. Returns:        None.
  623.  
  624. Description:    This routine is used to start playing a sample. You should
  625.                 only use sound effect channels to play samples.
  626.  
  627. See Also:       dStopVoice, dSetVoiceFreq, dSetVoiceVolume, dSetVoiceBalance,
  628.                 dGetVoicePos, dGetVoiceStatus.
  629.  
  630.  
  631. dPoll
  632. -----------------------------------------------------------------------------
  633. Function:       Updates the sound system output audio buffer.
  634.  
  635. Prototype:      void dPoll(void)
  636.  
  637. Parameters:     None.
  638.  
  639. Returns:        None.
  640.  
  641. Description:    This routine is used to update the output audio buffer
  642.                 and to poll your soundcard hardware. Must be called at
  643.                 least 50 times per second.
  644.                 You can use the timer interrupt services to call this
  645.                 routine periodically. If your program does not calls
  646.                 this routine enough times per second, the output audio
  647.                 will sound like a broken record.
  648.  
  649. See Also:       dInitTimer, dDoneTimer, dStartTimer, dStopTimer.
  650.  
  651.  
  652. dRegisterDriver
  653. -----------------------------------------------------------------------------
  654. Function:       Registers a lowlevel sound driver.
  655.  
  656. Prototype:      void dRegisterDriver(Driver *DriverPtr)
  657.  
  658. Parameters:     DriverPtr   - lowlevel driver structure
  659.  
  660. Returns:        None.
  661.  
  662. Description:    This routine is used to register new lowlevel sound drivers
  663.                 into the sound system. You must register all the drivers
  664.                 you want to use for playback. The sound system only knows
  665.                 registered sound drivers.
  666.  
  667. See Also:       dRegisterDrivers, dGetDriverStruc, dInit.
  668.  
  669.  
  670. dRegisterDrivers
  671. -----------------------------------------------------------------------------
  672. Function:       Registers all the static-link sound drivers.
  673.  
  674. Prototype:      void dRegisterDrivers(void)
  675.  
  676. Parameters:     None.
  677.  
  678. Returns:        None.
  679.  
  680. Description:    This function will register all the static-link drivers. It
  681.                 uses the dRegisterDriver function to register every driver.
  682.                 If you want to use dynamic-link audio drivers, you should
  683.                 use dLoadDriver and dRegisterDriver to load and register
  684.                 the dynamic-link audio drivers.
  685.  
  686. See Also:       dRegisterDriver, dLoadDriver.
  687.  
  688.  
  689. dResumeMusic
  690. -----------------------------------------------------------------------------
  691. Function:       Resumes playing the current music module.
  692.  
  693. Prototype:      int dResumeMusic(void)
  694.  
  695. Parameters:     None.
  696.  
  697. Returns:        Return zero on success.
  698.  
  699. Description:    Resumes playing the current music module.
  700.  
  701. See Also:       dStopMusic, dPauseMusic.
  702.  
  703.  
  704. dSetMusicVolume
  705. -----------------------------------------------------------------------------
  706. Function:       Set the music global volume.
  707.  
  708. Prototype:      void dSetMusicVolume(int Volume)
  709.  
  710. Parameters:     Volume  - master volume (0-255)
  711.  
  712. Returns:        None.
  713.  
  714. Description:    Used to change the global volume of the music. This routine
  715.                 does not changes the volume of the sound effect channels.
  716.  
  717. See Also:       dSetSoundVolume, dSetupVoices.
  718.  
  719.  
  720. dSetSoundVolume
  721. -----------------------------------------------------------------------------
  722. Function:       Set the sound effects global volume.
  723.  
  724. Prototype:      void dSetSoundVolume(int Volume)
  725.  
  726. Parameters:     Volume  - sound effects volume (0-255)
  727.  
  728. Returns:        None.
  729.  
  730. Description:    Used to change the global volume of the sound effects. This
  731.                 routine does not changes the volume of the music.
  732.  
  733. See Also:       dSetMusicVolume, dSetupVoices.
  734.  
  735.  
  736. dSetTimerSpeed
  737. -----------------------------------------------------------------------------
  738. Function:       Changes the timer interrupt speed.
  739.  
  740. Prototype:      void dSetTimerSpeed(int Speed)
  741.  
  742. Parameters:     Speed   - timer speed in ticks
  743.  
  744. Returns:        None.
  745.  
  746. Description:    This routine is used to change the speed of your timer
  747.                 interrupt service. The speed parameter is given in ticks.
  748.                 You can use the following formula to translate frequencies
  749.                 in hertz to ticks:
  750.  
  751.                         Ticks = 1193182 / Hertz
  752.  
  753.                 For example, if your timer service must be called 70 times
  754.                 per second:
  755.  
  756.                         dSetTimerSpeed(1193182/70)
  757.  
  758.                 Notice, that the old BIOS timer interrupt is always called
  759.                 at 18.2 hertz no matter the speed of your timer.
  760.  
  761.                 If you call this function with a speed of zero, then your
  762.                 timer will be synchronized with the VGA vertical retrace.
  763.  
  764. See Also:       dStartTimer, dStopTimer.
  765.  
  766.  
  767. dSetVoiceBalance
  768. -----------------------------------------------------------------------------
  769. Function:       Changes the balance or pan position of a voice.
  770.  
  771. Prototype:      void dSetVoiceBalance(int Voice, int Balance)
  772.  
  773. Parameters:     Voice   - voice number (0-31)
  774.                 Balance - balance (0-128)
  775.  
  776. Returns:        None.
  777.  
  778. Description:    Changes the balance of a specified voice. It only works
  779.                 for stereo soundcards. Also, you can choose to use stereo
  780.                 surround using the PAN_SURROUND value. You should only
  781.                 change the balance for sound effect channels.
  782.                 The following constants are defined to be used with this
  783.                 routine:
  784.  
  785.                 Constant        Value   Description
  786.                 ----------------------------------------
  787.                 PAN_LEFT        0x00    left balance
  788.                 PAN_RIGHT       0x80    right balance
  789.                 PAN_MIDDLE      0x40    middle balance
  790.                 PAN_SURROUND    0xA4    stereo surround
  791.  
  792.                 You can interpolate these values to do smooth pannings.
  793.                 Notice that the stereo surround does not work for GUS
  794.                 soundcards.
  795.  
  796. See Also:       dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceVolume,
  797.                 dGetVoicePos, dGetVoiceStatus.
  798.  
  799.  
  800. dSetVoiceFreq
  801. -----------------------------------------------------------------------------
  802. Function:       Changes the playback frequency for a specified voice.
  803.  
  804. Prototype:      void dSetVoiceFreq(int Voice, int Freq)
  805.  
  806. Parameters:     Voice   - voice number (0-31)
  807.                 Freq    - frequency (in hertz)
  808.  
  809. Returns:        None.
  810.  
  811. Description:    Changes the playback frequency of a voice. You should
  812.                 only change the frequencies of sound effect channels.
  813.  
  814. See Also:       dPlayVoice, dStopVoice, dSetVoiceVolume, dSetVoiceBalance,
  815.                 dGetVoicePos, dGetVoiceStatus.
  816.  
  817.  
  818. dSetVoiceVolume
  819. -----------------------------------------------------------------------------
  820. Function:       Changes the volume for a specified voice.
  821.  
  822. Prototype:      void dSetVoiceVolume(int Voice, int Volume)
  823.  
  824. Parameters:     Voice   - voice number (0-31)
  825.                 Volume  - volume level (0-64)
  826.  
  827. Returns:        None.
  828.  
  829. Description:    Changes the volume for a specified voice. Notice that the
  830.                 volume level goes from 0 to 64. The real volume will be
  831.                 computed using the global volume level. You should only
  832.                 change the volume of sound effect channels.
  833.  
  834. See Also:       dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceBalance,
  835.                 dGetVoicePos, dGetVoiceStatus.
  836.  
  837.  
  838. dSetupVoices
  839. -----------------------------------------------------------------------------
  840. Function:       Setup the amount of active voices.
  841.  
  842. Prototype:      void dSetupVoices(int NumVoices, int MasterVolume)
  843.  
  844. Parameters:     NumVoices       - number of active voices (1-32)
  845.                 MasterVolume    - master volume (16-255)
  846.  
  847. Returns:        None.
  848.  
  849. Description:    The sound system supports 32 digital sound channels. This
  850.                 routine is used to set the number of active voices that
  851.                 your program need to play music and/or sound effects.
  852.                 You should always use the minimum amount of active voices
  853.                 possible to improve the sound quality and to reduce the
  854.                 amount of CPU time required by the sound system.
  855.                 The master volume (or amplification factor) is used in
  856.                 8-bit output modes to boost the sound making it much
  857.                 more dynamic. The recommended value for this parameter
  858.                 is given by the following formula:
  859.  
  860.                         MasterVolume = Min(255,768/NumVoices)
  861.  
  862.                 The voices or channels are numbered from 0 to 31. When
  863.                 you start playing a music module the sound system uses
  864.                 the first N voices to play the music, where N is the
  865.                 number of tracks of the music module.
  866.                 If you want to play sounds and music simultanemously,
  867.                 you need to open more channels. You should not use the
  868.                 channels reserved for music to play your sounds.
  869.                 For example, if you are playing a 4-track music module
  870.                 and you need 2 channels for sound effects, you must have
  871.                 at least 6 active voices. The first voices 0-3 are used
  872.                 to play music, and voices 4-5 are used for sounds.
  873.  
  874. Important:      When you are going to change the amount of active voices,
  875.                 be sure to turn off the music and all the sound effect
  876.                 channels before calling this routine.
  877.  
  878. See Also:       dSetMusicVolume, dSetSoundVolume, dPlayMusic.
  879.  
  880.  
  881. dStartTimer
  882. -----------------------------------------------------------------------------
  883. Function:       Install a new timer service routine.
  884.  
  885. Prototype:      void dStartTimer(void (*Timer)(void), int Speed)
  886.  
  887. Parameters:     Timer   - timer handler address
  888.                 Speed   - timer speed in ticks
  889.  
  890. Returns:        None.
  891.  
  892. Description:    This routine will install your own handler to be called
  893.                 at a specified frequency. Usually you will need to use
  894.                 this routine to call dPoll enough times per second.
  895.  
  896. See Also:       dSetTimerSpeed, dStopTimer.
  897.  
  898.  
  899. dStopMusic
  900. -----------------------------------------------------------------------------
  901. Function:       Stop playing the current music module.
  902.  
  903. Prototype:      void dStopMusic(void)
  904.  
  905. Parameters:     None.
  906.  
  907. Returns:        None.
  908.  
  909. Description:    Stop playing the current music module.
  910.  
  911. See Also:       dPlayMusic, dPauseMusic, dResumeMusic.
  912.  
  913.  
  914. dStopTimer
  915. -----------------------------------------------------------------------------
  916. Function:       Deinstall the current timer handler.
  917.  
  918. Prototype:      void dStopTimer(void)
  919.  
  920. Parameters:     None.
  921.  
  922. Returns:        None.
  923.  
  924. Description:    This routine will deinstall the current timer handler.
  925.  
  926. See Also:       dStartTimer.
  927.  
  928.  
  929. dStopVoice
  930. -----------------------------------------------------------------------------
  931. Function:       Stop playing a sample.
  932.  
  933. Prototype:      void dStopVoice(int Voice)
  934.  
  935. Parameters:     Voice   - voice number (0-31)
  936.  
  937. Returns:        None.
  938.  
  939. Description:    This routine is used to stop playing a sample. You should
  940.                 only stop samples that are being played on sound effect
  941.                 channels.
  942.  
  943. See Also:       dPlayVoice, dSetVoiceFreq, dSetVoiceVolume, dSetVoiceBalance,
  944.                 dGetVoicePos, dGetVoiceStatus.
  945.  
  946.  
  947.  
  948. 2. Structures:
  949.  
  950. Driver structure
  951. -----------------------------------------------------------------------------
  952. Function:       Lowlevel sound driver structure.
  953.  
  954. Declaration:    typedef struct {
  955.                     dword   Magic;
  956.                     dword   Next;
  957.                     byte    ID;
  958.                     byte    Modes;
  959.                     char    Name[32];
  960.                     word    Port;
  961.                     byte    IrqLine;
  962.                     byte    DmaChannel;
  963.                     word    MinRate;
  964.                     word    MaxRate;
  965.                     word    BufferLength;
  966.                     void    *ProcTablePtr;
  967.                     void    *DriverPtr;
  968.                     word    *ParmTablePtr;
  969.                 } Driver;
  970.  
  971. Description:    This structure holds all the information related to any
  972.                 lowlevel sound driver. This structure is used to register
  973.                 sound drivers.
  974.  
  975. Fields:         ID              - sound driver identifier
  976.                 Modes           - sound driver capabilities
  977.                 Name            - sound driver long name
  978.                 Port            - default base I/O port address
  979.                 IrqLine         - default IRQ interrupt line
  980.                 DmaChannel      - default DMA output channel
  981.                 MinRate         - minimum sample rate
  982.                 MaxRate         - maximum sample rate
  983.                 ParmTablePtr    - list of Port/IRQ/DMA parameters
  984.  
  985.                 Here is the list of driver identifiers:
  986.  
  987.                 Constant        Description
  988.                 --------------------------------------
  989.                 ID_NONE         No Sound
  990.                 ID_SB           Sound Blaster
  991.                 ID_SB201        Sound Blaster 2.01
  992.                 ID_SBPRO        Sound Blaster Pro
  993.                 ID_SB16         Sound Blaster 16
  994.                 ID_PAS          Pro Audio Spectrum
  995.                 ID_PASPLUS      Pro Audio Spectrum+
  996.                 ID_PAS16        Pro Audio Spectrum 16
  997.                 ID_WSS          Windows Sound System
  998.                 ID_GUS          Gravis UltraSound
  999.  
  1000.                 The sound driver capabilities bit flags are:
  1001.  
  1002.                 Constant        Description
  1003.                 ---------------------------------------------------
  1004.                 AF_8BITS        8-bits per sample
  1005.                 AF_16BITS       16-bits per sample
  1006.                 AF_MONO         mono output mode
  1007.                 AF_STEREO       stereo output mode
  1008.                 AF_NODRAM       samples stored in system memory
  1009.                 AF_DRAM         samples stored in soundcard memory
  1010.  
  1011. See Also:       dRegisterDriver, dGetDriverStruc.
  1012.  
  1013.  
  1014. DSM structure
  1015. -----------------------------------------------------------------------------
  1016. Function:       Module information structure.
  1017.  
  1018. Declaration:    typedef struct {
  1019.                     Song    Header;
  1020.                     Sample  **Samples;
  1021.                     Pattern **Patterns;
  1022.                 } DSM;
  1023.  
  1024. Description:    This structure is used to hold all the information related
  1025.                 to a music module file. It includes a header with global
  1026.                 information about the module, the main music sequence, and
  1027.                 a list of instruments and patterns structures.
  1028.  
  1029. See Also:       Song, Sample, Pattern structures.
  1030.  
  1031.  
  1032. MHdr structure
  1033. -----------------------------------------------------------------------------
  1034. Function:       Internal music player structure.
  1035.  
  1036. Declaration:    typedef struct {
  1037.                     dword   MusicVolume;
  1038.                     dword   SoundVolume;
  1039.                     MTrk    Tracks[MAXVOICES];
  1040.                     byte    NumTracks;
  1041.                     byte    NumVoices;
  1042.                     byte    OrderPos;
  1043.                     byte    OrderLen;
  1044.                     byte    ReStart;
  1045.                     byte    PattNum;
  1046.                     byte    PattRow;
  1047.                     byte    BreakFlag;
  1048.                     byte    Tempo;
  1049.                     byte    TempoCount;
  1050.                     byte    BPM;
  1051.                     byte    SyncMark;
  1052.                     byte    Status;
  1053.                     byte    DriverStatus;
  1054.                     void    *PattPtr;
  1055.                     DSM     *SongPtr;
  1056.                 } MHdr;
  1057.  
  1058. Description:    The music player uses this structure while playing a music
  1059.                 module file. It holds all the information required to keep
  1060.                 track of the song while it's being played.
  1061.  
  1062. Fields:         MusicVolume     - current music volume
  1063.                 SoundVolume     - current sound effects volume
  1064.                 Tracks          - array of track structures
  1065.                 NumTracks       - number of active tracks
  1066.                 NumVoices       - number of active voices
  1067.                 OrderPos        - current order positionm
  1068.                 OrderLen        - order list length
  1069.                 ReStart         - restart order position
  1070.                 PattNum         - current pattern number
  1071.                 PattRow         - current pattern row
  1072.                 BreakFlag       - break pattern flags
  1073.                 Tempo           - current tempo value
  1074.                 TempoCount      - tempo counter
  1075.                 BPM             - current BPM value
  1076.                 SyncMark        - last sync mark seen
  1077.                 Status          - music player status
  1078.                 DriverStatus    - sound driver status
  1079.  
  1080.  
  1081. MTrk structure
  1082. -----------------------------------------------------------------------------
  1083. Function:       Internal playback music track information.
  1084.  
  1085. Declaration:    typedef struct {
  1086.                     byte    Note;
  1087.                     byte    Sample;
  1088.                     byte    Volume;
  1089.                     byte    Balance;
  1090.                     word    Effect;
  1091.                     word    Rate;
  1092.                     byte    VUMeter;
  1093.                     byte    Flags;
  1094.                     byte    Reserved[38];
  1095.                 } MTrk;
  1096.  
  1097. Description:    This structure is used by the music player to keep track
  1098.                 of every track of the music.
  1099.  
  1100. Fields:         Note            - note number (1=C-0,96=B-7)
  1101.                 Sample          - sample number
  1102.                 Volume          - volume level
  1103.                 Balance         - stereo balance
  1104.                 Effect          - protracker command
  1105.                 Rate            - middle-c frequency
  1106.                 VUMeter         - volume unit meter
  1107.  
  1108.                 The balance is any value between PAN_LEFT and PAN_RIGHT,
  1109.                 or the special value PAN_SURROUND for stereo surround.
  1110.  
  1111.                 The Effect fields holds one of the following standard
  1112.                 Protracker commands:
  1113.  
  1114.                     Command         Description
  1115.                 -----------------------------------------------------
  1116.                     0xy             arpeggio
  1117.                     1xx             portamento up
  1118.                     2xx             portamento down
  1119.                     3xx             tone portamento
  1120.                     4xy             vibrato
  1121.                     5xx             tone portamento and volume slide
  1122.                     6xx             vibrato and volume slide
  1123.                     7xy             tremolo
  1124.                     8xx             set fine pan position
  1125.                     9xx             sample offset
  1126.                     Axy             volume slide
  1127.                     Bxx             jump position
  1128.                     Cxx             set volume
  1129.                     Dxx             break pattern
  1130.                     E0x             set filter
  1131.                     E1x             fine portamento up
  1132.                     E2x             fine portamento down
  1133.                     E3x             glissando control
  1134.                     E4x             vibrato control
  1135.                     E5x             set finetune
  1136.                     E6x             pattern loop
  1137.                     E7x             tremolo control
  1138.                     E8x             set pan position
  1139.                     E9x             retrig note
  1140.                     EAx             fine volume up
  1141.                     EBx             fine volume down
  1142.                     ECx             note cut
  1143.                     EDx             note delay
  1144.                     EEx             pattern delay
  1145.                     EFx             invert loop
  1146.                     Fxx             set speed/tempo
  1147.  
  1148.                 Some of the above commands are not suppported in the
  1149.                 current version of the sound system.
  1150.  
  1151. See Also;       dGetMusicStruc, MHdr structure.
  1152.  
  1153.  
  1154. Pattern structure
  1155. -----------------------------------------------------------------------------
  1156. Function:       Pattern sheet information.
  1157.  
  1158. Declaration:    typedef struct {
  1159.                     word    Length;
  1160.                     byte    Data[1];
  1161.                 } Pattern;
  1162.  
  1163. Description:    Used to store music patterns.
  1164.  
  1165. See Also:       DSM structure.
  1166.  
  1167.  
  1168. RIFF structures
  1169. -----------------------------------------------------------------------------
  1170. Function:       RIFF file header and block structures.
  1171.  
  1172. Declarations:   typedef struct {
  1173.                     dword   ID;
  1174.                     dword   Length;
  1175.                     dword   Type;
  1176.                 } RiffHeader;
  1177.  
  1178.                 typedef struct {
  1179.                     dword   ID;
  1180.                     dword   Length;
  1181.                 } RiffBlock;
  1182.  
  1183. Description:    These structures are used to parse RIFF files. The sound
  1184.                 system module and sample file formats are RIFF-based.
  1185.  
  1186. See Also:       DSM, Song, Sample, Pattern structures.
  1187.  
  1188.  
  1189. Sample structure
  1190. -----------------------------------------------------------------------------
  1191. Function:       Sample information structure.
  1192.  
  1193. Declaration:    typedef struct {
  1194.                     char    FileName[13];
  1195.                     word    Flags;
  1196.                     byte    Volume;
  1197.                     dword   Length;
  1198.                     dword   LoopStart;
  1199.                     dword   LoopEnd;
  1200.                     void    *DataPtr;
  1201.                     word    Rate;
  1202.                     word    Voice;
  1203.                     char    SampleName[28];
  1204.                 } Sample;
  1205.  
  1206. Description:    This structure holds all the information related to a sample
  1207.                 or instrument. All the samples and/or instruments are loaded
  1208.                 in memory using this structure.
  1209.  
  1210. Fields:         FileName        - DOS file name
  1211.                 Flags           - sample bit flags
  1212.                 Volume          - default volume
  1213.                 Length          - sample length
  1214.                 LoopStart       - loop start point
  1215.                 LoopEnd         - loop end point
  1216.                 DataPtr         - data address
  1217.                 Rate            - middle-C frequency
  1218.                 SampleName      - sample name
  1219.  
  1220.                 The flags are used only when the module is loaded in memory.
  1221.                 These are the bit flags you can use:
  1222.  
  1223.                 Constant        Description
  1224.                 ----------------------------------------
  1225.                 SF_8BITS        8-bits per sample
  1226.                 SF_16BITS       16-bits per sample
  1227.                 SF_UNSIGNED     unsigned samples
  1228.                 SF_SIGNED       signed samples
  1229.                 SF_LOOPED       forward looping enabled
  1230.                 SF_DELTA        delta packed samples
  1231.  
  1232.                 Notice that 16-bit samples are not supported in the current
  1233.                 version of the sound system.
  1234.  
  1235. See Also:       dLoadSample, dImportSample, DSM structure.
  1236.  
  1237.  
  1238. Song structure
  1239. -----------------------------------------------------------------------------
  1240. Function:       Song information structure.
  1241.  
  1242. Declaration:    typedef struct {
  1243.                     char    ModuleName[28];
  1244.                     word    FileVersion;
  1245.                     word    Flags;
  1246.                     word    OrderPos;
  1247.                     word    ReStart;
  1248.                     word    NumOrders;
  1249.                     word    NumSamples;
  1250.                     word    NumPatterns;
  1251.                     word    NumTracks;
  1252.                     byte    GlobalVolume;
  1253.                     byte    MasterVolume;
  1254.                     byte    InitTempo;
  1255.                     byte    InitBPM;
  1256.                     byte    ChanMap[MAXTRACKS];
  1257.                     byte    Orders[MAXORDERS];
  1258.                 } Song;
  1259.  
  1260. Description:    This structure is used to hold information about the module
  1261.                 file (number of samples, patterns, sequence list, etc).
  1262.  
  1263. Fields:         ModuleName      - song or module name
  1264.                 OrderPos        - starting order position
  1265.                 ReStart         - restart order position
  1266.                 NumOrders       - number of orders
  1267.                 NumSamples      - number of samples
  1268.                 NumPatterns     - number of patterns
  1269.                 NumTracks       - number of tracks
  1270.                 GlobalVolume    - default global volume
  1271.                 MasterVolume    - default master volume
  1272.                 InitTempo       - initial tempo value
  1273.                 InitBPM         - initial BPM value
  1274.                 ChanMap         - tracks default balances
  1275.                 Orders          - order list
  1276.  
  1277.                 This structure is used within a DSM module structure.
  1278.  
  1279. See Also:       DSM, Sample, Pattern structures.
  1280.  
  1281.  
  1282. SoundCard structure
  1283. -----------------------------------------------------------------------------
  1284. Function:       Soundcard configuration structure.
  1285.  
  1286. Declaration:    typedef struct {
  1287.                     byte    ID;
  1288.                     byte    Modes;
  1289.                     word    Port;
  1290.                     byte    IrqLine;
  1291.                     byte    DmaChannel;
  1292.                     word    SampleRate;
  1293.                     char    DriverName[16];
  1294.                 } SoundCard;
  1295.  
  1296. Description:    This structure holds the current soundcard's configuration,
  1297.                 it's used to initialize the sound system.
  1298.  
  1299. Fields:         ID              - soundcard identifier
  1300.                 Modes           - output mode bit flags
  1301.                 Port            - base I/O port address
  1302.                 IrqLine         - IRQ interrupt line
  1303.                 DmaChannel      - DMA output channel
  1304.                 SampleRate      - sample rate
  1305.  
  1306. See Also:       dInit.
  1307.  
  1308.  
  1309.