Inside Macintosh: QuickTime Reference

ExtendedSoundComponentData

The ExtendedSoundComponentData structure is shown below.

struct ExtendedSoundComponentData { SoundComponentData desc; /*description of sound buffer*/ long recordSize; /*size of this record in bytes*/ long extendedFlags; /*flags for extended record*/ long bufferSize; /*size of buffer in bytes*/ }; typedef struct ExtendedSoundComponentData ExtendedSoundComponentData; typedef ExtendedSoundComponentData * ExtendedSoundComponentDataPtr;

Its first element is a classic SoundComponentData allowing a pointer to a SoundComponentData to also serve as a pointer to an ExtendedSoundComponentData. This means that in parts of the component API where a SoundComponentData was passed or retrieved, it is now possible to find an ExtendedSoundComponentData.

To determine if the SoundComponentData is an ExtendedSoundComponentData, you can check the following flag in the flags field of a SoundComponentData:

kExtendedSoundData = (1 << 14)

If set, you know that the structure consists at least of the fields shown here -- namely, recordSize, extendedFlags and bufferSize. In the future, it is expected that the set of fields will be extended, so it is important to confirm that the fields you want to read are actually present. To that end, you should compare the recordSize field's value to the size of a record containing the fields you need. If the record size is smaller, then you know the fields are missing.

The bufferSize field holds the number of bytes in the buffer. This allows for cases where the number of bytes isn't derivable directly from the number of samples. In the cases where it is derivable, this information is at worst redundant. The extendedFlags holds fields relating to the interpretation of the new fields and to the interpretation of the old fields. The fields defined currently are:

kExtendedSoundSampleCountNotValid = 1L << 0 kExtendedSoundBufferSizeValid = 1L << 1

The kExtendedSoundBufferSizeValid flag indicates if the bufferSize field is valid. If not set, then you shouldn't use the bufferSize field's value. In the case of the 4.1 sound media handler, the buffer size is now passed so this flag is set.

The kExtendedSoundSampleCountNotValid is slightly more unusual. This allows a buffer of audio of bufferSize bytes to not declare the number of audio samples that it will generate. Note that if this flag is set, the bufferSize field must be valid and the kExtendedSoundBufferSizeValid flag must be set.

While this ability to not specify the sample count is of little use in the sound media handler case where the sample references already describe the durations of all the samples, it may prove more useful in other cases.

One such case involves sound conversion where the decompressor is asked to generate audio samples until a source buffer is exhausted. Instead of requiring that we know the number of source audio samples before decompression, this allows the client to just feed audio until there is no more. Another case involves playback where durations aren't known. In both cases, it seems advantageous to not have to ask the decompressor to parse all the data just to determine the number of audio samples only to pass that number back to the decompressor so that it can parse and actually decode the data.

From the sound decompressor's point of view, this is the most important new structure and is available from the decompressor's call to its source's SoundComponentGetSourceData call. Keep in mind that the structure returned may not be an ExtendedSoundComponentData, so be careful to check.

Inside Macintosh: QuickTime Reference