Inside Macintosh: Sound /

Chapter 5 - Sound Components / Sound Components Reference

Data Structures

Sound Parameter Blocks

The Sound Manager passes a component's SoundComponentPlaySourceBuffer function a sound parameter block that describes the source data to be modified or sent to a sound output device. A sound parameter block is defined by the SoundParamBlock data type.

struct SoundParamBlock {
   long                 recordSize;    /*size of this record in bytes*/
   SoundComponentData   desc;          /*description of sound buffer*/
   Fixed                rateMultiplier;/*rate multiplier*/
   short                leftVolume;    /*volume on left channel*/
   short                rightVolume;   /*volume on right channel*/
   long                 quality;       /*quality*/
   ComponentInstance    filter;        /*filter*/
   SoundParamProcPtr    moreRtn;       /*routine to call to get more data*/
   SoundParamProcPtr    completionRtn; /*buffer complete routine*/
   long                 refCon;        /*user refcon*/
   short                result;        /*result*/
};
typedef struct SoundParamBlock SoundParamBlock;
typedef SoundParamBlock *SoundParamBlockPtr;

Field Description

recordSize

The length, in bytes, of the sound parameter block.

desc

A sound component data record that describes the format, size, and location of the sound data. See "Sound Component Data Records" on page 5-29 for a description of the sound component data record.

rateMultiplier

A multiplier to be applied to the playback rate of the sound. This field contains an unsigned fixed-point number. If, for example, this field has the value 2.0, the sound is played back at twice the rate specified in the sampleRate field of the sound component data record contained in the desc field.

leftVolume

The playback volume for the left channel. You specify a volume with 16-bit value, where 0 (hexadecimal 0x0000) represents no volume and 256 (hexadecimal 0x0100) represents full volume. You can overdrive a channel's volume by passing volume levels greater than 0x0100.

rightVolume

The playback volume for the right channel. You specify a volume with 16-bit value, where 0 (hexadecimal 0x0000) represents no volume and 256 (hexadecimal 0x0100) represents full volume. You can overdrive a channel's volume by passing volume levels greater than 0x0100.

quality

The level of quality for the sound. This value usually determines how much processing should be applied during audio data processing (such as rate conversion and decompression) to increase the output quality of the sound.

filter

Reserved for future use. You should set this field to nil.

moreRtn

A pointer to a callback routine that is called to retrieve another buffer of audio data. This field is used internally by the Sound Manager.

completionRtn

A pointer to a callback routine that is called when the sound has finished playing. This field is used internally by the Sound Manager.

refCon

A value that is to be passed to the callback routines specified in the moreRtn and completionRtn fields. You can use this field to pass information (for example, the address of a structure) to a callback routine.

result

The status of the sound that is playing. The value 1 indicates that the sound is currently playing. The value 0 indicates that the sound has finished playing. Any negative value indicates that some error has occurred.