Retired Document
Important: This sample code may not represent best practices for current development. The project may use deprecated symbols and illustrate technologies and techniques that are no longer recommended.
DBFF.h
/* |
File: DBFF.h |
Contains: Headers for routines called to play a sound from disk using DBFF functions. |
Written by: Mark Cookson |
Copyright: Copyright © 1996-1999 by Apple Computer, Inc., All Rights Reserved. |
You may incorporate this Apple sample source code into your program(s) without |
restriction. This Apple sample source code has been provided "AS IS" and the |
responsibility for its operation is yours. You are not permitted to redistribute |
this Apple sample source code as "Apple sample source code" after having made |
changes. If you're going to re-distribute the source, we require that you make |
it clear in the source that the code was descended from Apple sample source |
code, but that you've made changes. |
Change History (most recent first): |
8/13/1999 Karl Groethe Updated for Metrowerks Codewarror Pro 2.1 |
*/ |
/* |
This file contains the function prototypes so that if you built the source |
into a library you would only need this file and DBFF_Errors.h to compile |
your source. This also provides for some data hiding by typedef'ing the |
SoundInfoPtr into just a Ptr. This file is not needed if you are not using |
the code to build a library. |
*/ |
#ifndef __DBFF__ |
#define __DBFF__ |
#include <Sound.h> |
#include "DBFF_Errors.h" |
#define kFreeMem 1 |
#define kCloseFile 2 |
typedef Ptr SoundInfoPtr; |
/* Function definitions */ |
/* Purpose: This creates a new SoundInfo structure and initializes |
it by calling ASoundInit. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
SoundInfoPtr ASoundNew (OSErr *theErr); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Display a StandardFile dialog to select an AIFF file. |
Open the file selected by the user. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundGetFileToPlay (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Checks a file to see if its header can be parsed |
and the file can be played. |
This will return an error if the sound will not play, |
returning noErr means that sound will play. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundCanThisPlay (CInfoPBPtr theFileInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Wrapper function called to get ready to play a sound. |
Use this if you want to make sure that there is enough |
memory to play the sound. |
Side Effects: This will call routines that will allocate memory needed |
to all of the various structures needed by the Sound Manager |
and memory to be used as the sounds' buffers. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundReadyForPlaying (SoundInfoPtr theSoundInfo, |
unsigned long bufferSize); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Call this after you have called ASoundReadyForPlaying to |
start playing the sound you prepaired. |
Side Effects: Starts the sound playing. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundPlay (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Wrapper function called to start playing a sound. |
Use this if you are pretty sure the sound will play, or |
just don't care specifically what goes wrong. |
Side Effects: This will call routines that will allocate memory needed |
to all of the various structures needed by the Sound Manager |
and memory to be used as the sounds' buffers. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundStartPlaying (SoundInfoPtr theSoundInfo, |
unsigned long bufferSize); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Stops the currently playing sound. |
Side Effects: Stopping the currently playing sound will cause the |
sound completion routine to run. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundStop (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Wrapper so the user doesn't have to keep track of if |
the sound is playing or not. |
Side Effects: If resuming a sound and the user had also called |
ASoundPauseForAdjust this will reinstall the sound |
completion callback. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundPause (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: If the sound is paused, resume playing. If the sound is |
playing, pause playing. |
This differs from ASoundPause because it actually stops |
the sound instead of pausing it. When the sound is |
paused for adjusting you can reset where the sound will |
next start playing from without having to play the |
remainder of the current buffer. This routine is used |
for the QuickTime style playing. |
Side Effects: Removes the callback from the sound channel because |
otherwise while adjusting the sound the Sound Manager |
would call our clean up routine. |
When resuming a sound ASoundStartPlaying will install |
our callback routine if necessary (if the sound wasn't |
already paused). |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundPauseForAdjust (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Sound is done playing, dispose of the memory we no |
longer need. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundDonePlaying (SoundInfoPtr theSoundInfo, |
unsigned long options); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Returns the channel for the sound in case you want to |
send it specific commands. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
SndChannelPtr ASoundGetChan (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Returns the name of the file containing the currently |
playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundGetSoundName (SoundInfoPtr theSoundInfo, |
Str255 theName); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the number of the current buffer |
(in the range 1 to ASoundGetNumBuffers()) of the |
currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
long ASoundGetCurBuffer (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Sets which buffer should be the next buffer to play |
from (in the range 1 to ASoundGetNumBuffers()) |
for the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundSetCurBuffer (SoundInfoPtr theSoundInfo, |
long newValue); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the number of buffers that the currently playing |
sound will need to play in its entirety. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
long ASoundGetNumBuffers (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the length (in bytes) of the currently playing |
sound. This number does not include any header bytes. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
long ASoundGetNumTotalBytes (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the number of bytes that will be played by the end |
of the current buffer of the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
long ASoundGetBytesCopied (SoundInfoPtr theSoundInfo); |
/* |
Purpose: Sets the location in the file where the next buffer |
should be filled from for the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundSetBytesCopied (SoundInfoPtr theSoundInfo, |
long newValue); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the size of a buffer of the currently playing |
sound. Multiply by two to know how much memory is |
reserved for buffering the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
long ASoundGetBufferSize (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the UPP for the function that should be called when |
the currently playing sound finishes. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
SndCallBackUPP ASoundGetSoundCallBack (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Sets the function that should be called when the the |
currently playing sound finishes. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundSetSoundCallBack (SoundInfoPtr theSoundInfo, |
void* newValue); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Says to play the currently playing sound backwards |
(reverses the sound in the buffer). |
Side Effects: Takes effect when the next sound buffer gets filled. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundPlayBackwards (SoundInfoPtr theSoundInfo, |
Boolean newValue); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Returns true if the currently playing sound's buffer |
is set to be reversed. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
Boolean ASoundIsBackwards (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Returns true if the sound has finished playing. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
Boolean ASoundIsDone (SoundInfoPtr theSoundInfo); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Changes the volume of the currently playing sound. |
The values you pass in are added to the current values. |
Negitive values will decrease the volume, positive values |
will increase the volume. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundChangeVolume (SoundInfoPtr theSoundInfo, |
unsigned short leftVol, |
unsigned short rightVol); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the volume of the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundGetVolume (SoundInfoPtr theSoundInfo, |
unsigned short *leftVol, |
unsigned short *rightVol); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Sets the volume of the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundSetVolume (SoundInfoPtr theSoundInfo, |
unsigned short leftVol, |
unsigned short rightVol); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the rate multiplier of the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundGetRateMul (SoundInfoPtr theSoundInfo, |
UnsignedFixed *theRateMul); |
/*-----------------------------------------------------------------------*/ |
/* |
Purpose: Gets the rate multiplier of the currently playing sound. |
Side Effects: None. |
*/ |
/*-----------------------------------------------------------------------*/ |
OSErr ASoundSetRateMul (SoundInfoPtr theSoundInfo, |
UnsignedFixed theRateMul); |
/*-----------------------------------------------------------------------*/ |
#endif |
Copyright © 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-03-14