Inside Macintosh: Sound /

Chapter 2 - Sound Manager / Sound Manager Reference

Sound Manager Routines / Allocating and Releasing Sound Channels

SndNewChannel

You can use the SndNewChannel 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 the Gestalt 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 pass NIL as the userRoutine parameter, then any callBackCmd commands sent to this channel are ignored.

DESCRIPTION

The SndNewChannel function internally allocates memory to store a queue of sound commands. If you pass a pointer to NIL as the chan 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 to NIL as the chan parameter, then that parameter must contain a pointer to a sound channel record.

If you pass a pointer to NIL as the chan parameter, then the amount of memory the SndNewChannel 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 to NIL, the amount of memory allocated is determined by the qLength 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 the synth parameter and the signature of the desired sound output device component in the init 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 the SndNewChannel 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 the SndNewChannel 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.