Carbon


Sound Command Numbers A

Header: Sound.h

enum {
    nullCmd = 0,
    quietCmd = 3,
    flushCmd = 4,
    reInitCmd = 5,
    waitCmd = 10,
    pauseCmd = 11,
    resumeCmd = 12,
    callBackCmd = 13,
    syncCmd = 14,
    availableCmd = 24,
    versionCmd = 25,
    volumeCmd = 46,
    getVolumeCmd = 47,
    clockComponentCmd = 50,
    getClockComponentCmd = 51,
    scheduledSoundCmd = 52,
    linkSoundComponentsCmd = 53,
    soundCmd = 80,
    bufferCmd = 81,
    rateMultiplierCmd = 86,
    getRateMultiplierCmd = 87
};

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 function 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 function.

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

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. 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. GetVolumeCmd is available only in Sound Manager versions 3.0 and later.

param1: 0 (ignored on input and output)

param2: pointer to volume data

clockComponentCmd
getClockComponentCmd
scheduledSoundCmd
linkSoundComponentsCmd
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. 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

rateMultiplierCmd
getRateMultiplierCmd

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 function. 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 function.

The cmd field of the SndCommand data structure described in SndCommand, 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.

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.

See “Sound Command Numbers B” for more command constants.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)