Inside Macintosh: Sound /

Chapter 2 - Sound Manager / Sound Manager Reference

Constants

Sound Command Numbers

You can perform many sound-related operations by sending sound commands to a sound channel. For example, to change the volume of a sound that is currently playing, you can send the ampCmd sound command to the channel using the SndDoImmediate routine. Similarly, to change the volume of all sounds subsequently to be played in a sound channel, you can send the volumeCmd sound command to that channel using the SndDoCommand routine.

The cmd field of the SndCommand data structure (described on page 2-99) specifies the sound command you want to execute. The param1 and param2 fields of that structure contain any additional information that might be needed to complete the command. One or both of these parameter fields might be ignored by a particular sound command. In some cases, the Sound Manager returns information to your application in one of the parameter fields.

IMPORTANT

In general, you'll use either SndDoCommand or SndDoImmediate to send sound commands to a sound channel. With several commands, however, you must use the SndControl function to issue the sound command. In Sound Manager version 3.0 and later, however, you virtually never need to use SndControl because the commands that require it are either no longer supported (for example, availableCmd, totalLoadCmd, and loadCmd) or are obsolete (for example, versionCmd). The sound commands specific to the SndControl function are documented here for completeness only.

The sound commands available to your application are defined by constants.

CONST
   nullCmd           = 0;        {do nothing}
   quietCmd          = 3;        {stop a sound that is playing}
   flushCmd          = 4;        {flush a sound channel}
   reInitCmd         = 5;        {reinitialize a sound channel}
   waitCmd           = 10;       {suspend processing in a channel}
   pauseCmd          = 11;       {pause processing in a channel}
   resumeCmd         = 12;       {resume processing in a channel}
   callBackCmd       = 13;       {execute a callback procedure}
   syncCmd           = 14;       {synchronize channels}
   availableCmd      = 24;       {see if initialization options are }
                                 { supported}
   versionCmd        = 25;       {determine version}
   totalLoadCmd      = 26;       {report total CPU load}
   loadCmd           = 27;       {report CPU load for a new channel}
   freqDurationCmd   = 40;       {play a note for a duration}
   restCmd           = 41;       {rest a channel for a duration}
   freqCmd           = 42;       {change the pitch of a sound
   ampCmd            = 43;       {change the amplitude of a sound}
   timbreCmd         = 44;       {change the timbre of a sound}
   getAmpCmd         = 45;       {get the amplitude of a sound}
   volumeCmd         = 46;       {set volume}
   getVolumeCmd      = 47;       {get volume}
   waveTableCmd      = 60;       {install a wave table as a voice}
   soundCmd          = 80;       {install a sampled sound as a voice}
   bufferCmd         = 81;       {play a sampled sound}
   rateCmd           = 82;       {set the pitch of a sampled sound}
   getRateCmd        = 85;       {get the pitch of a sampled sound}

Constant descriptions

nullCmd

Do nothing.
param1: 0 (ignored on input and output)
param2: 0 (ignored on input and output)

quietCmd

Stop the sound that is currently playing. You should send quietCmd by using SndDoImmediate.
param1: 0 (ignored on input and output)
param2: 0 (ignored on input and output)

flushCmd

Remove all commands currently queued in the specified sound channel. A flushCmd command does not affect any sound that is currently in progress. You should send flushCmd by using SndDoImmediate.
param1: 0 (ignored on input and output)
param2: 0 (ignored on input and output)

reInitCmd

Reset the initialization parameters specified in param2 for the specified channel.
param1: 0 (ignored on input and output)
param2: initialization parameters

waitCmd

Suspend further command processing in a channel until the specified duration has elapsed. To achieve sounds longer than 32,767 half-milliseconds, Pascal programmers can pass a negative number in param1, in which case the sound plays for 32,767 half-milliseconds plus the absolute value of param1.
param1: duration in half-milliseconds (0 to 65,565)
param2: 0 (ignored on input and output)

pauseCmd

Pause any further command processing in a channel until resumeCmd is received.
param1: 0 (ignored on input and output)
param2: 0 (ignored on input and output)

resumeCmd

Resume command processing in a channel that was previously paused by pauseCmd.
param1: 0 (ignored on input and output)
param2: 0 (ignored on input and output)

callBackCmd

Execute the callback procedure specified as a parameter to the SndNewChannel function. Both param1 and param2 are application-specific; you can use these two parameters to send data to your callback routine.
param1: application-defined
param2: application-defined

syncCmd

Synchronize multiple channels of sound. A syncCmd command is held in the specified channel, suspending all further command processing. The param2 parameter contains an identifier that is arbitrary. Each time the Sound Manager receives syncCmd, it decrements the count parameter for each channel having that identifier. When the count for a specific channel reaches 0, command processing in that channel resumes.
param1: count
param2: identifier

availableCmd

Return 1 in param1 if the Sound Manager supports the initialization options specified in param2 and 0 otherwise. However, the Sound Manager might support certain initialization parameters in general but not on a specific machine. You should send availableCmd using the SndControl function.
param1: 0 on input; result of command on output
param2: initialization parameters

versionCmd

Previously, this command determined which version of a sound data format is available. The result is returned in param2. The high word of the result indicates the major revision number, and the low word indicates the minor revision number. For example, version 2.0 of a data format would be returned as $00020000. However, this command is obsolete, and your application should not rely on it. You send versionCmd by using the SndControl function.
param1: 0 (ignored on input and output)
param2: 0 on input; version on output

totalLoadCmd

Previously, this command determined the total CPU load factor for all existing sound activity and for a new sound channel having the initialization parameters specified in param2. However, this command is obsolete, and your application should not rely on it. You send totalLoadCmd by using the SndControl function.
param1: 0 on input, load factor on output
param2: initialization parameters

loadCmd

Previously, this command determined the CPU load factor that would be incurred by a new channel of sound having the initialization parameters specified in param2. The load factor returned in param1 is the percentage of CPU processing power that the specified sound channel would require. However, this command is obsolete, and your application should not rely on it. You send loadCmd by using the SndControl function.
param1: 0 on input, load factor on output
param2: initialization parameters

freqDurationCmd

Play the note specified in param2 for the duration specified in param1. To achieve sounds longer than 32,767 half-milliseconds, Pascal programmers can pass a negative number in param1, in which case the sound plays for 32,767 half-milliseconds plus the absolute value of param1. The param2 parameter must contain a value in the range 0 to 127. If you want the note to stop playing after the duration specified in param1, you must send quietCmd after freqDurationCmd.
param1: duration in half-milliseconds (0 to 65,565)
param2: desired frequency

restCmd

Rest a channel for a specified duration. The duration is specified in half-milliseconds in param1. To achieve sounds longer than 32,767 half-milliseconds, Pascal programmers can pass a negative number in param1, in which case the sound plays for 32,767 half-milliseconds plus the absolute value of param1.
param1: duration in half-milliseconds (0 to 65,565)
param2: 0 (ignored on input and output)

freqCmd

Change the frequency (or pitch) of a sound. If no sound is currently playing, then freqCmd causes the Sound Manager to begin playing indefinitely at the frequency specified in param2. If, however, no instrument is installed in the channel and you attempt to play either wave-table or sampled-sound data, no sound is produced. The param2 parameter must contain a value in the range 0 to 127. The freqCmd command is identical to the freqDurationCmd command, except that no duration is specified to a freqCmd command.
param1: 0 (ignored on input and output)
param2: desired frequency

ampCmd

Change the amplitude (or loudness) of a sound. If no sound is currently playing, then ampCmd sets the amplitude of the next sound to be played. You specify the amplitude in param1; the amplitude should be an integer in the range 0 to 255.
param1: desired amplitude
param2: 0 (ignored on input and output)

timbreCmd

Change the timbre (or tone) of a sound currently being defined using square-wave data. A timbre value of 0 produces a clear tone; a timbre value of 254 produces a buzzing tone. You can use timbreCmd only for sounds defined using square-wave data.
param1: desired timbre (0 to 254)
param2: 0 (ignored on input and output)

getAmpCmd

Determine the current amplitude (or loudness) of a sound. The amplitude is returned in an integer variable whose address you pass in param2 and is in the range 0 to 255.
param1: 0 (ignored on input and output)
param2: pointer to amplitude variable

volumeCmd

Set the right and left volumes of the specified sound channel to the volumes specified in the high and low words of param2. The value $0100 represents full volume, and $0080 represents half volume. You can specify values larger than $0100 to overdrive the volume. For example, setting param2 to $02000200 sets the volume on both left and right speakers to twice full volume. Note, however, that volumeCmd is available only in Sound Manager versions 3.0 and later.
param1: 0 (ignored on input and output)
param2: high word is right volume, low word is left volume

getVolumeCmd

Get the current right and left volumes of the specified sound channel. The volumes are returned in the high and low words of the long integer pointed to by param2. The value $0100 represents full volume, and $0080 represents half volume. Note, however, that getVolumeCmd is available only in Sound Manager versions 3.0 and later.
param1: 0 (ignored on input and output)
param2: pointer to volume data

waveTableCmd

Install a wave table as a voice in the specified channel. The param1 parameter specifies the length of the wave table, and the param2 parameter is a pointer to the wave-table data itself. You can use waveTableCmd only for sounds defined using wave-table data.
param1: length of wave table
param2: pointer to wave-table data

soundCmd

Install a sampled sound as a voice in a channel. If the high bit of the command is set, param2 is interpreted as an offset from the beginning of the 'snd ' resource containing the command to the sound header. If the high bit is not set, param2 is interpreted as a pointer to the sound header. You can use the soundCmd command only with noncompressed sampled-sound data. You can also use soundCmd to preconfigure a sound channel, so that you can later send sound commands to it at interrupt time.
param1: 0 (ignored on input and output)
param2: offset or pointer to sound header

bufferCmd

Play a buffer of sampled-sound data. If the high bit of the command is set, param2 is interpreted as an offset from the beginning of the 'snd ' resource containing the command to the sound header. If the high bit is not set, param2 is interpreted as a pointer to the sound header. You can use bufferCmd only with sampled-sound data. Note that sending a bufferCmd resets the rate of the channel to 1.0.
param1: 0 (ignored on input and output)
param2: offset or pointer to sound header

rateCmd

Set the rate of a sampled sound that is currently playing, thus effectively altering its pitch and duration. Your application can set a rate of 0 to pause a sampled sound that is playing. The new rate is set to the value specified in param2, which is interpreted relative to 22 kHz. (For example, to set the rate to 44 kHz, pass $00020000 in param2; see Listing 2-4 on page 2-26 for sample code that uses rateCmd.) You can use rateCmd only with sampled-sound data.
param1: 0 (ignored on input and output)
param2: desired rate of sound

getRateCmd

Determine the sample rate of the sampled sound currently playing. The current rate of the channel is returned in a Fixed variable whose address you pass in param2 of the sound command. The values returned are always relative to the 22 kHz sampling rate, as with the rateCmd sound command. You can use getRateCmd only with sampled-sound data, and you should send it by using SndDoImmediate.
param1: 0 (ignored on input and output)
param2: pointer to rate variable