Important: Inside Macintosh: Sound is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.
SndNewChannel
You can use theSndNewChannel
function to allocate a new sound channel.
FUNCTION SndNewChannel (VAR chan: SndChannelPtr; synth: Integer; init: LongInt; userRoutine: ProcPtr): OSErr;
chan
- A pointer to a sound channel record. You can pass a pointer whose value is
NIL
to force the Sound Manager to allocate the sound channel record internally.synth
- The sound data type you intend to play on this channel. If you do not want to specify a specific data type, pass 0 in this parameter. You might do this if you plan to use the channel to play a single sound resource that itself specifies the sound's data type.
init
- The desired initialization parameters for the channel. If you cannot determine what types of sounds you will be playing on the channel, pass 0 in this parameter. Only sounds defined by wave-table data and sampled-sound data currently use the
init
options. You can use theGestalt
function to determine if a sound feature (such as stereo output) is supported by a particular computer.userRoutine
- A pointer to a callback procedure that the Sound Manager executes whenever it receives a
callBackCmd
command. If you passNIL
as theuserRoutine
parameter, then anycallBackCmd
commands sent to this channel are ignored.DESCRIPTION
TheSndNewChannel
function internally allocates memory to store a queue of sound commands. If you pass a pointer toNIL
as thechan
parameter, the function also allocates a sound channel record in your application's heap and returns a pointer to that record. If you do not pass a pointer toNIL
as thechan
parameter, then that parameter must contain a pointer to a sound channel record.If you pass a pointer to
NIL
as thechan
parameter, then the amount of memory theSndNewChannel
function allocates to store the sound commands is enough to store 128 sound commands. However, if you pass a pointer to the sound channel record rather than a pointer toNIL
, the amount of memory allocated is determined by theqLength
field of the sound channel record. Thus, if you wish to control the size of the sound queue, you must allocate your own sound channel record. Regardless of whether you allocate your own sound channel record, the Sound Manager allocates memory for the sound command queue internally.The
synth
parameter specifies the sound data type you intend to play on this channel. You can use these constants to specify the data type:
CONST squareWaveSynth = 1; {square-wave data} waveTableSynth = 3; {wave-table data} sampledSynth = 5; {sampled-sound data}In Sound Manager versions earlier than version 3.0, only one data type can be produced at any one time. As a result,SndNewChannel
may fail if you attempt to open a channel specifying a data type other than the one currently being played.To specify a sound output device other than the current sound output device, pass the value
kUseOptionalOutputDevice
in thesynth
parameter and the signature of the desired sound output device component in theinit
parameter.
CONST kUseOptionalOutputDevice = -1;The ability to redirect output away from the current sound output device is intended for use by specialized applications that need to use a specific sound output device. In general, your application should always send sound to the current sound output device selected by the user.SPECIAL CONSIDERATIONS
Because theSndNewChannel
function allocates memory, you should not call it at interrupt time.RESULT CODES
noErr 0 No error resProblem -204 Problem loading the resource badChannel -205 Channel is corrupt or unusable SEE ALSO
For an example of a routine that uses theSndNewChannel
function, see Listing 2-1 on page 2-20.For information on the format of a callback procedure, see "Callback Procedures" on page 2-152.