home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / Caveman Sound System / CMSoundSystem.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-09-11  |  15.1 KB  |  370 lines  |  [TEXT/KAHL]
  1. /*****************************************************************************
  2.  * FILE:        CMSoundSystem.h
  3.  * AUTHOR:        David Hay
  4.  * CREATED:        March 9, 1995
  5.  * DESCRIPTION:    Interface to the Caveman Sound System.
  6.  *    
  7.  * Copyright © 1995 David Hay
  8.  *
  9.  * Permission to use, copy, and distribute this software and its documentation
  10.  * for any purpose is hereby granted without fee,  provided that (i) the above
  11.  * copyright notices  and  this permission notice  appear in all copies of the
  12.  * software  and  related documentation,  and (ii) the names of David Hay  and
  13.  * Caveman Creations may not be used in any advertising or publicity  relating
  14.  * to the software without the specific, prior written permission of David Hay
  15.  *
  16.  * THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
  17.  * IMPLIED  OR  OTHERWISE,  INCLUDING,  WITHOUT  LIMITATION,  ANY WARRANTY  OF
  18.  * MERCHANTABILITY  OR  FITNESS FOR  A PARTICULAR PURPOSE.  IN NO EVENT  SHALL
  19.  * DAVID HAY  OR  CAVEMAN CREATIONS  BE LIABLE  FOR  ANY SPECIAL,  INCIDENTAL,
  20.  * INDIRECT  OR  CONSEQUENTIAL DAMAGES OF ANY KIND,  OR ANY DAMAGES WHATSOEVER
  21.  * RESULTING FROM LOSS OF USE, DATA OR PROFITS,  WHETHER OR NOT ADVISED OF THE
  22.  * POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN
  23.  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  24.  *****************************************************************************/
  25.  
  26. #ifndef __CMSOUNDSYSTEM__
  27. #define __CMSOUNDSYSTEM__
  28.  
  29. #ifndef __SOUND__
  30. #include <Sound.h>
  31. #endif
  32.  
  33. #define kMaxChannels    20        /* The maximum number of channels allowed */
  34. #define kMaxSounds        50        /* Maximum number of sounds that may be registered */
  35. #define kMaxMusicLen    128        /* Maximum length of a song sequence. */
  36. #define kNoSound        (-1)    /* Reference number for no sound at all */
  37. #define kSoundResource    (-2)    /* Reference number of an unregistered sound */
  38. #define kNoLoop            (-1)    /* In a music sequence, indicates no looping */
  39. #define kMusicResType    'MUSL'    /* Resource type for a music list */
  40. #define kAsynchronous    true    /* Constant to define asychronous play */
  41.  
  42.  
  43.  
  44. /*****************************************************************************
  45. ** PlaySequence        -- Describes a sequence of sounds to play in order to
  46. **                       produce a piece of music.
  47. **
  48. **        loopStart        - the position in the sequence to jump to after the
  49. **                          sequence as finished.
  50. **        sequenceLength    - the number of sounds to play in the sequence.
  51. **        sequence[]        - the list of sounds to play. This array determines
  52. **                          the order of sounds to play, allowing a sound
  53. **                          to be repeated several times in a piece of music.
  54. **/
  55. typedef struct PlaySequence
  56. {
  57.     short    loopStart;
  58.     short    sequenceLength;
  59.     short    sequence[1];        /* Variable sized */
  60. } PlaySequence, *PlaySequencePtr, **PlaySequenceHandle;
  61.  
  62.  
  63.  
  64. /*----------------------- INITIALIZATION/DEALLOCATION -----------------------*/
  65.  
  66. extern OSErr
  67. CMSInitSound( short numChannels );
  68. /*
  69.  *    Initialize the sound system.
  70.  *
  71.  *    ON ENTRY:    'numChannels' is a number greater than 0
  72.  *    ON EXIT:    The sound system has been initialized to provide 'numChannels'
  73.  *                channels of sound.
  74.  *                Any errors are returned.
  75.  *****************************************************************************/
  76.  
  77. extern void
  78. CMSDisposeSound( void );
  79. /*
  80.  *    Dispose of any registered sound and internal data used by the sound
  81.  *    system.  Any sound system functions should not be used after calling
  82.  *    this function.
  83.  *
  84.  *    ON ENTRY:    The sound system has been previously initialized
  85.  *    ON EXIT:    Any data used by the sound system is disposed of.
  86.  *****************************************************************************/
  87.  
  88.  
  89. /*---------------------------- CHANNEL MANAGEMENT ---------------------------*/
  90.  
  91. extern OSErr
  92. CMSCloseChannel( short channelNum );
  93. /*
  94.  *    Closes sound channel number 'channelNum'.  The channel is still allocated,
  95.  *    but sound may not be played through it.  To reopen the channel, call
  96.  *    CMSOpenChannel()
  97.  *
  98.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  99.  *                    available channels [as passed to CMSInitSound()]
  100.  *                The sound system has been initialized
  101.  *    ON EXIT:    The channel number 'channelNum' has been closed.
  102.  *                Any errors are returned.
  103.  *****************************************************************************/
  104.  
  105. extern OSErr
  106. CMSCloseAllChannels( void );
  107. /*
  108.  *    Closes all of the open channels.  The channels are still allocated, but
  109.  *    sound may not be played through them.  To reopen a specific channel, call
  110.  *    CMSOpenChannel().  To reopen all channels, call CMSOpenAllChannels().
  111.  *
  112.  *    ON ENTRY:    The sound system has been initialized
  113.  *    ON EXIT:    All open sound channels have been closed.
  114.  *                Any errors are returned.
  115.  *****************************************************************************/
  116.  
  117. extern OSErr
  118. CMSOpenChannel( short channelNum );
  119. /*
  120.  *    Opens channel number 'channelNum'.  After opening a channel, sound may be
  121.  *    played through that sound channel.  If the sound channel is alreay open,
  122.  *    nothing is done.
  123.  *
  124.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  125.  *                    available channels [as passed to CMSInitSound()]
  126.  *                The sound system has been initialized
  127.  *    ON EXIT:    The channel, 'channelNum' is opened and ready to play sounds
  128.  *                Any errors are returned.
  129.  *****************************************************************************/
  130.  
  131. extern OSErr
  132. CMSOpenAllChannels( void );
  133. /*
  134.  *    Opens all currently closed sound channels.  After opening a sound channel,
  135.  *    sound may be played on that sound channel.
  136.  *
  137.  *    ON ENTRY:    The sound system has been initialized.
  138.  *    ON EXIT:    All allocated sound channels have been opened.
  139.  *                Any errors are returned.
  140.  *****************************************************************************/
  141.  
  142. extern OSErr
  143. CMSStopSound( short channelNum );
  144. /*
  145.  *    Stops any currently playing sounds on sound channel 'channelNum'
  146.  *
  147.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  148.  *                    available sound channels [as passed to CMSInitSound()]
  149.  *    ON EXIT:    Any sounds playing on channel, 'channelNum' are stopped. If
  150.  *                the sound playing on the sound channel was a sound resource,
  151.  *                the resource is unlocked so that it may be purged.
  152.  *****************************************************************************/
  153.  
  154. extern void
  155. CMSIdleSoundTask( void );
  156. /*
  157.  *    Handles any housecleaning tasks the sound system may need to perform. It
  158.  *    should be called before playing a sound resource.
  159.  *
  160.  *    ON ENTRY:    The sound system has been initialized
  161.  *    ON EXIT:    Any routine chores the sound system have been performed.
  162.  *****************************************************************************/
  163.  
  164. extern OSErr
  165. CMSGetSoundPlaying( short channelNum, short* refNum );
  166. /*
  167.  *    Get the reference number of the sound currently playing on a sound channel.
  168.  *
  169.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  170.  *                    available sound channels [as passed to CMSInitSound()]
  171.  *                'refNum' points to location to store the currently playing
  172.  *                    sound reference number.
  173.  *    ON EXIT:    The sound playing on the channel, 'channelNum' is returned in
  174.  *                the area pointed to by 'refNum'.  If no sounds are currently
  175.  *                playing, 'kNoSound' is returned in 'refNum'.  If the currently
  176.  *                playing sound is a sound resource, 'kSoundResource' is returned
  177.  *****************************************************************************/
  178.  
  179. extern OSErr
  180. CMSWaitForSilence( short channelNum );
  181. /*
  182.  *    Wait for a sound channel to fall silent.  This should not be called on
  183.  *    a sound channel that is playing music with a loop as it will never return.
  184.  *
  185.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  186.  *                    available sound channels [as passed to CMSInitSound()]
  187.  *                    that is not playing music with a loop.
  188.  *    ON EXIT:    The channel, 'channelNum' has fallen silent and is no longer
  189.  *                producing sound.
  190.  *                Any errors are returned.
  191.  *****************************************************************************/
  192.  
  193.  
  194. /*--------------------------- SOUND DATA MANAGEMENT -------------------------*/
  195.  
  196. extern OSErr
  197. CMSRegisterSound( SndListHandle theSound, short* refNum );
  198. /*
  199.  *    Registers a sound with the sound system for later playback.
  200.  *
  201.  *    ON ENTRY:    'theSound' is a valid sound handle.
  202.  *                'refNum' points to space to store a sound reference number.
  203.  *    ON EXIT:    The sound handle 'theSound' has been registered with the
  204.  *                sound system.  The sound may be played back at a later time
  205.  *                by calling CMSPlaySound() with the returned reference number.
  206.  *                Any errors are returned.
  207.  *****************************************************************************/
  208.  
  209. extern OSErr
  210. CMSRemoveSound( short refNum );
  211. /*
  212.  *    Removes a previously registered sound from the sound system.
  213.  *
  214.  *    ON ENTRY:    'refNum' is the reference number of a sound previously
  215.  *                    registered with the sound system with either
  216.  *                    CMSRegisterSound() or CMSLoadSound().
  217.  *    ON EXIT:    The sound referenced by 'refNum' is removed from the sound
  218.  *                system and disposed of.
  219.  *                Any errors are returned.
  220.  *****************************************************************************/
  221.  
  222. extern OSErr
  223. CMSLoadSound( short soundID, short* refNum );
  224. /*
  225.  *    Loads a sound from the current resource file and registers it with the
  226.  *    sound system.
  227.  *
  228.  *    ON ENTRY:    'soundID' is the resource ID of a valid 'snd ' resource.
  229.  *                'refNum' points to space to store a sound reference number.
  230.  *    ON EXIT:    The sound resource ('snd ') number 'soundID' is loaded from
  231.  *                the current resource file and registered with the sound
  232.  *                system.
  233.  *                Any error codes are returned.
  234.  *****************************************************************************/
  235.  
  236. extern OSErr
  237. CMSPlaySound( short refNum, short channelNum );
  238. /*
  239.  *    Plays a registered sound on a sound channel.
  240.  *
  241.  *    ON ENTRY:    'refNum' is the reference number of a sound previously
  242.  *                    registered with the sound system with either
  243.  *                    CMSRegisterSound() or CMSLoadSound().
  244.  *                'channelNum' is a positive number less than the number of
  245.  *                    available sound channels [as passed to CMSInitSound()]
  246.  *    ON EXIT:    The sound referenced by 'refNum' has begun playing on sound
  247.  *                channel, 'channelNum'.
  248.  *                Any error codes are returned.
  249.  *****************************************************************************/
  250.  
  251. extern OSErr
  252. CMSPlaySoundResource( short resID, short channelNum, Boolean async );
  253. /*
  254.  *    Plays a sound from a resource file.  This function is meant to provide
  255.  *    the functionality of SndPlay() through the sound system.
  256.  *
  257.  *    ON ENTRY:    'resID' is the number of a valid 'snd ' resrouce to play
  258.  *                'channelNum' is a positive number less than the number of
  259.  *                    available sound channels [as passed to CMSInitSound()]
  260.  *                'async' is a boolean value indicating whether the sound should
  261.  *                    be played asynchronosly or not.
  262.  *    ON EXIT:    The sound resource has begun playing on channel, 'channelNum'.
  263.  *                If 'async' is false, then CMSPlaySoundResource() will not
  264.  *                return until the sound has finished playing in it's entirety.
  265.  *                Any error codes are returned.
  266.  *****************************************************************************/
  267.  
  268.  
  269. /*----------------------------- MUSIC MANAGEMENT ----------------------------*/
  270.  
  271. extern OSErr
  272. CMSLoadMusic( short musicID );
  273. /*
  274.  *    Loads the sounds and music sequence data as defined by the music list
  275.  *    resource 'musicID'.  The music may then be played with a call to
  276.  *    CMSPlayMusic().
  277.  *
  278.  *    ON ENTRY:    'musicID' is the number of a valid 'MUSL' resource to load.
  279.  *    ON EXIT:    Loads the music described by the 'MUSL' resource, 'musicID'.
  280.  *                Each of the sounds listed in the play sequence is loaded and
  281.  *                registered with the sound system. The internal play sequence
  282.  *                is set up in preparation for playing music.
  283.  *****************************************************************************/
  284.  
  285. extern OSErr
  286. CMSRemoveMusic( void );
  287. /*
  288.  *    Removes the currently loaded piece of music from the sound system.  Any
  289.  *    sounds associated with playing music are ungregistered and freed.
  290.  *
  291.  *    ON ENTRY:    The sound system has been initialized
  292.  *    ON EXIT:    A piece of music previously loaded with CMSLoadMusic() is
  293.  *                removed from the system.  Any sounds associated with the
  294.  *                music are removed from the system and freed.  If no music
  295.  *                had been previously loaded, control is returned to the caller
  296.  *                immediately with no errors.
  297.  *****************************************************************************/
  298.  
  299. extern OSErr
  300. CMSPlayMusic( short channelNum );
  301. /*
  302.  *    Begins a piece of music previously loaded with CMSLoadMusic().
  303.  *
  304.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  305.  *                    available sound channels [as passed to CMSInitSound()]
  306.  *    ON EXIT:    The music previously loaded has begun to play on sound channel
  307.  *                'channelNum'.   The music will continue until it reaches the
  308.  *                end of the piece (if there are no loops).  Or until the sound
  309.  *                on the channel is silenced with a call to CMSStopSound().
  310.  *****************************************************************************/
  311.  
  312.  
  313. /*----------------------------- UTILITY ROUTINES ----------------------------*/
  314.  
  315. extern SoundHeaderPtr
  316. CMSGetSoundHeader( SndListHandle sndHandle );
  317. /*
  318.  *    Obtains a pointer to the sound header in the given sound resource. Because
  319.  *    a pointer into the handle is returned, the handle is locked and should not
  320.  *    be unlocked until the sound header is no longer needed. A pointer to a
  321.  *    sampled sound header is returned even if the sound header is actually an
  322.  *    extended sound header or a compressed sound header.
  323.  *
  324.  *    ON ENTRY:    'sndHandle' is a valid sound handle.
  325.  *    ON EXIT:    A pointer to a valid sound header in the sound 'sndHandle' is
  326.  *                returned. If there is not a sound header in the given resource,
  327.  *                then NULL is returned.
  328.  *****************************************************************************/
  329.  
  330. extern OSErr
  331. CMSGetSoundHeaderOffset( SndListHandle soundHandle, long* theOffset );
  332. /*
  333.  *    Traverses a sound resource until it reaches the sound data.    It returns
  334.  *    the offset in bytes from the beginning of a sound resource to the sound
  335.  *    header.
  336.  *
  337.  *    ON ENTRY:    'soundHandle' is a valid sound handle.
  338.  *                'theOffset' points to a location to store the header offset.
  339.  *    ON EXIT:    The offset in the sound handle 'soundHandle' is returned in
  340.  *                the space pointed to by 'theOffset'.
  341.  *                Any errors are returned.
  342.  *****************************************************************************/
  343.  
  344.  
  345. /*----------------------------- INQUIRY ROUTINES ----------------------------*/
  346.  
  347. extern Boolean
  348. CMSHasNewSoundManager( void );
  349. /*
  350.  *    Determines if the current sound manager is the "new" one.  The "new"
  351.  *    Sound Manager contains the _SoundDispatch trap and is version 2.0 or
  352.  *    greater.
  353.  *
  354.  *    ON ENTRY:    no preconditions
  355.  *    ON EXIT:    Returns true if the "new" sound manager is present on the
  356.  *                current machine.
  357.  *****************************************************************************/
  358.  
  359. extern Boolean
  360. CMSHasMultipleChannels( void );
  361. /*
  362.  *    Determines if the currently running sound manager is capable of supporting
  363.  *    multiple channels of sound.
  364.  *
  365.  *    ON ENTRY:    no preconditions
  366.  *    ON EXIT:    Returns true if the currently running sound manager is capable
  367.  *                of supporting multiple channels of sound.
  368.  *****************************************************************************/
  369.  
  370. #endif /* __CMSOUNDSYSTEM__ */