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.
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 theampCmd
sound command to the channel using theSndDoImmediate
routine. Similarly, to change the volume of all sounds subsequently to be played in a sound channel, you can send thevolumeCmd
sound command to that channel using theSndDoCommand
routine.The
cmd
field of theSndCommand
data structure (described on page 2-99) specifies the sound command you want to execute. Theparam1
andparam2
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.
The sound commands available to your application are defined by constants.
- IMPORTANT
- In general, you'll use either
SndDoCommand
orSndDoImmediate
to send sound commands to a sound channel. With several commands, however, you must use theSndControl
function to issue the sound command. In Sound Manager version 3.0 and later, however, you virtually never need to useSndControl
because the commands that require it are either no longer supported (for example,availableCmd
,totalLoadCmd
, andloadCmd
) or are obsolete (for example,versionCmd
). The sound commands specific to theSndControl
function are documented here for completeness only.
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 usingSndDoImmediate
.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 sendflushCmd
by usingSndDoImmediate
.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 parameterswaitCmd
- 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 ofparam1
.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. Bothparam1
andparam2
are application-specific; you can use these two parameters to send data to your callback routine.param1
: application-definedparam2
: application-definedsyncCmd
- Synchronize multiple channels of sound. A
syncCmd
command is held in the specified channel, suspending all further command processing. Theparam2
parameter contains an identifier that is arbitrary. Each time the Sound Manager receivessyncCmd
, it decrements thecount
parameter for each channel having that identifier. When the count for a specific channel reaches 0, command processing in that channel resumes.param1
: countparam2
: identifieravailableCmd
- Return 1 in
param1
if the Sound Manager supports the initialization options specified inparam2
and 0 otherwise. However, the Sound Manager might support certain initialization parameters in general but not on a specific machine. You should sendavailableCmd
using theSndControl
function.param1
: 0 on input; result of command on outputparam2
: initialization parametersversionCmd
- 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 sendversionCmd
by using theSndControl
function.param1
: 0 (ignored on input and output)param2
: 0 on input; version on outputtotalLoadCmd
- 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 sendtotalLoadCmd
by using theSndControl
function.param1
: 0 on input, load factor on outputparam2
: initialization parametersloadCmd
- 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 inparam1
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 sendloadCmd
by using theSndControl
function.param1
: 0 on input, load factor on outputparam2
: initialization parametersfreqDurationCmd
- Play the note specified in
param2
for the duration specified inparam1
. To achieve sounds longer than 32,767 half-milliseconds, Pascal programmers can pass a negative number inparam1
, in which case the sound plays for 32,767 half-milliseconds plus the absolute value ofparam1
. Theparam2
parameter must contain a value in the range 0 to 127. If you want the note to stop playing after the duration specified inparam1
, you must sendquietCmd
afterfreqDurationCmd
.param1
: duration in half-milliseconds (0 to 65,565)param2
: desired frequencyrestCmd
- 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 inparam1
, in which case the sound plays for 32,767 half-milliseconds plus the absolute value ofparam1
.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 inparam2
. 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. Theparam2
parameter must contain a value in the range 0 to 127. ThefreqCmd
command is identical to thefreqDurationCmd
command, except that no duration is specified to afreqCmd
command.param1
: 0 (ignored on input and output)param2
: desired frequencyampCmd
- 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 inparam1
; the amplitude should be an integer in the range 0 to 255.param1
: desired amplitudeparam2
: 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 variablevolumeCmd
- 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, settingparam2
to $02000200 sets the volume on both left and right speakers to twice full volume. Note, however, thatvolumeCmd
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 volumegetVolumeCmd
- 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, thatgetVolumeCmd
is available only in Sound Manager versions 3.0 and later.param1
: 0 (ignored on input and output)param2
: pointer to volume datawaveTableCmd
- Install a wave table as a voice in the specified channel. The
param1
parameter specifies the length of the wave table, and theparam2
parameter is a pointer to the wave-table data itself. You can usewaveTableCmd
only for sounds defined using wave-table data.param1
: length of wave tableparam2
: pointer to wave-table datasoundCmd
- 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 thesoundCmd
command only with noncompressed sampled-sound data. You can also usesoundCmd
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 headerbufferCmd
- 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 usebufferCmd
only with sampled-sound data. Note that sending abufferCmd
resets the rate of the channel to 1.0.param1
: 0 (ignored on input and output)param2
: offset or pointer to sound headerrateCmd
- 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 inparam2
; see Listing 2-4 on page 2-26 for sample code that usesrateCmd
.) You can userateCmd
only with sampled-sound data.param1
: 0 (ignored on input and output)param2
: desired rate of soundgetRateCmd
- 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 inparam2
of the sound command. The values returned are always relative to the 22 kHz sampling rate, as with therateCmd
sound command. You can usegetRateCmd
only with sampled-sound data, and you should send it by usingSndDoImmediate
.param1
: 0 (ignored on input and output)param2
: pointer to rate variable