Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TMediaSequence
Inherited By:
TAudioIFFSequence
TQuickTimeAudioSequence
Purpose:
Represents raw digital sound data. It is an abstraction for a sequence of sound samples. To use the metaphor of a cassette and a cassette recorder, TAudioSequence represents a cassette. TAudioSequence can be handed to a TAudioPlayer, which can play the cassette. TAudioPlayer is like a tape recorder with a cassette in it. TAudioSequence has member functions that are used to access and modify the sound samples in the sequence. These functions use a memory-mapped interface, where the audio data is mapped into memory and directly accessed by the client. An audio sequence can be read-only.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
TAudioIFFSequence derives from this class.
Deriving classes must override the following pure virtual member functions: GetDurationInSamples, SeekToSample, GetPositionInSamples, Read, Write, and CreateSubrange.
Deriving classes may need to override IsReadOnly (default behavior is to return true), and assignment, Hash, IsEqual, and streaming operators if new data members are added.
Other responsibilities: Deriving classes must specify the audio type(s) they support and the number of channels they contain by calling AddAudioType and SetNumberOfChannels.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TAudioSequence ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called by Runtime to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::SetChosenAudioType
virtual void SetChosenAudioType (const TAudioType & theChosenType)
Interface Category:
API.
Purpose:
Some sequences can supply data in a number of formats. This function sets the chosen type for the audio sequence. When reading data from a sequence, data of the chosen type is passed back. When writing data, the sequence expects the data of the chosen type.
Calling Context:
Called by deriving classes to specify default data format you want it to provide audio data. Requested type must have been previously added by a call to AddAudioType. Also called by base class stream-in operator.
You can call CreatePreferredTypeList to see what types of audio data this sequence supports. You can call ChoosePreferredType to have the sequence return what it thinks should be the chosen type, given a set of possible types.
Parameters:
- const TAudioType & theChosenType -The type you want the data supplied in.
Return Value:
None.
Exceptions:
Throws TTimeMediaException::kInvalidType if the requested type is not supported by the sequence.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::CreateChosenAudioType
TAudioType * CreateChosenAudioType () const
Interface Category:
API.
Purpose:
Some sequences can supply data in a number of formats. This function returns a copy of the chosen type for the audio sequence. When reading data from a sequence, data of the chosen type is passed back. When writing data, the sequence expects the data of the chosen type.
Calling Context:
Call directly to find out in what format the sequence will provide audio data. You can call CreatePreferredTypeList to see what types of audio data this sequence supports. You can call ChoosePreferredType to have the sequence return what it thinks should be the chosen type, given a set of possible types.
Parameters:
Return Value:
A pointer to a copy of the selected audio type.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The client is responsible for deleting the storage associated with the pointer returned.
Member Function: TAudioSequence::IsReadOnly
virtual bool IsReadOnly () const
Interface Category:
API.
Purpose:
Returns true if the sequence cannot be written.
Calling Context:
Call directly to see if the sequence cannot be written.
Parameters:
Return Value:
Returns true if the sequence cannot be written, otherwise returns false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::GetNumberOfChannels
long GetNumberOfChannels () const
Interface Category:
API.
Purpose:
Returns the number of interleaved channels in the audio data. Some sequences store stereo and other multichannel formats as interleaved samples. For stereo, the left channel is stored first followed by the right channel.
Calling Context:
Call directly to determine how many channels are in the audio sequence.
Parameters:
Return Value:
long -The number of channels of interleaved audio.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::GetDurationInSamples
virtual TSamples :: Position GetDurationInSamples () const
Interface Category:
API.
Purpose:
Returns the total number of samples in the audio sequence.
Calling Context:
Call directly to determine how long the sequence is. Used by GetDuration.
Parameters:
Return Value:
virtual TSamples :: Position -The number of samples.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual void Seek (const TTime & position)
Interface Category:
API.
Purpose:
Seeks to a specific time in the sequence.
Calling Context:
Call directly to seek to a time.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::SeekToSample
virtual void SeekToSample (TSamples :: Position position)
Interface Category:
API.
Purpose:
Seeks to a specific sample position in the sequence.
Calling Context:
Call directly to seek to a specific sample. Used by Seek.
Parameters:
- TSamples :: Position position -The position to seek to.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::GetPosition
virtual void GetPosition (TTime & position) const
Interface Category:
API.
Purpose:
Fills in the TTime with the current position in the file.
Calling Context:
Call directly to get the position in units of time.
Parameters:
- TTime & position -The time to be filled in with the current time.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::GetPositionInSamples
virtual TSamples :: Position GetPositionInSamples () const
Interface Category:
API.
Purpose:
Returns the current position in the file.
Calling Context:
Call directly to get the position in samples. Used by GetPosition.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TSamples::Position Read (TMemorySurrogate & fillThis, TSamples::Position numberOfSamplesToRead)
Interface Category:
API.
Purpose:
Reads a block of memory from the sequence starting at the current Seek position. The Seek position is moved to the end of the block actually read.
Calling Context:
Call directly when reading data. Used by SoundServer.
Parameters:
- TMemorySurrogate & fillThis -The block of memory to receive data from the sequence.
- TSamples::Position numberOfSamplesToRead -The desired number of samples to read from the sequence.
Return Value:
TSamples::Position -The number of samples actually read.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TSamples::Position Write (const TMemorySurrogate & dataToWrite, TSamples::Position numberOfSamplesToWrite)
Interface Category:
API.
Purpose:
Writes a block of memory into the sequence starting at the current Seek position. The Seek position is moved to the end of the block actually written. The Duration of the sequence is updated if changed by Write.
Calling Context:
Call directly when writing data. Used by SoundServer.
Parameters:
- const TMemorySurrogate & dataToWrite -The block of memory to copy into the sequence.
- TSamples::Position numberOfSamplesToWrite -The desired number of samples to write into the sequence.
Return Value:
TSamples::Position -The number of samples actually written.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual void DeepCopy (TAudioSequence &) const
Interface Category:
API.
Purpose:
Copies the audio data from one audio sequence to another. All data in this sequence is lost.
Calling Context:
Call directly to copy audio data from one sequence to another. This is an expensive operation, as potentially megabytes of audio data are copied.
Parameters:
Return Value:
None.
Exceptions:
Throws TTimeMediaException::kInvalidType if the sequence being copied to is of an incompatible type.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::CreateSubrange
virtual TMediaSequence * CreateSubrange (const TMediaRange & range) const
Interface Category:
API.
Purpose:
Creates a new audio sequence that is a subset of the audio sequence. The range specifies the start time and duration of the subset.
Calling Context:
Call directly to create a subset of an audio sequence. Unlike DeepCopy, CreateSubrange does not copy actual data, just references to the data. This is an inexpensive operation.
Parameters:
- const TMediaRange & range -A range specifying the start and duration of the subset.
Return Value:
TMediaSequence* -A new audio sequence that is a subset of the original.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::GetDuration
void GetDuration (TTime & duration) const
Interface Category:
API.
Purpose:
Returns the duration of the audio sequence.
Calling Context:
Call directly to determine how long the sequence is.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::CreatePreferredTypeList
virtual void CreatePreferredTypeList (TSequenceOf<TMediaType> & typeList) const
Interface Category:
API.
Purpose:
Some sequences can supply data in a number of formats. This function fills in the TSequenceOf parameter with the types of audio data the audio sequence supports. The audio data types are represented by TAudioType.
Calling Context:
Call directly to determine at runtime what types of audio data a sequence supports. Used by TAudioPlayer.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::ChoosePreferredType
virtual TMediaType * ChoosePreferredType (const TSequenceOf<TMediaType> & theChoices) const
Interface Category:
API.
Purpose:
Given a collection of audio types, returns the type that the sequence can most easily supply. Some sequences can supply data in a number of formats.
Calling Context:
Call directly to find out the format the audio sequence would prefer to supply its data in. After calling this, you can then call SetChosenType to tell the audio sequence to supply the data in this format.
Parameters:
Return Value:
TMediaType* -A pointer to a TAudioType that the sequence would prefer to supply its data in or NIL if no selection can be made. The instance of TAudioType pointed to is one of the types found in the passed in the TSequenceOf parameter. Don't delete it unless you created it.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::operator<<=
virtual TStream & operator <<= (TStream & fromWhere)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Call directly to stream in data. Used by SoundServer.
Parameters:
- TStream & fromWhere -The stream the object streams itself in from.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws TInvalidVersionError if the versions don't match.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::operator>>=
virtual TStream & operator >>=(TStream & toWhere) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Call directly to stream out data. Used by SoundServer.
Parameters:
- TStream & toWhere -The stream the object streams itself out to.
Return Value:
Returns a reference to the stream the object streams itself out to.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TAudioSequence ()
- TAudioSequence (const TAudioSequence &)
Interface Category:
API.
Purpose:
- Default constructor.
- Copy constructor.
Calling Context:
- Protected -Not to be called directly. Called by deriving classes when creating an undefined object that will immediately be assigned to or streamed into.
- Protected -Not to be called directly. Called by deriving classes to copy an object.
Parameters:
- Takes no parameters.
- const TAudioSequence & -The audio sequence to copy.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
TAudioSequence & operator =(const TAudioSequence &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call directly when an object is assigned to another compatible object.
Parameters:
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::SetNumberOfChannels
virtual void SetNumberOfChannels (long numberOfChannels)
Interface Category:
API.
Purpose:
Sets the number of interleaved audio channels. Some sequences store stereo and other multichannel formats as interleaved samples. For stereo, the left channel is stored first, followed by the right channel.
Calling Context:
Called by deriving classes to set the number of channels. This value is stored in TAudioSequence.
Parameters:
- long numberOfChannels -The number of interleaved audio channels.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAudioSequence::AddAudioType
virtual void AddAudioType (const TAudioType & newType)
Interface Category:
API.
Purpose:
Adds the audio type to the sequence list of preferred types.
Calling Context:
Called by deriving classes to add each supported audio type to the preferred type list. This list is maintained by TAudioSequence.
Parameters:
- const TAudioType & newType -The audio type to add.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual long Hash () const
Interface Category:
API.
Purpose:
Generates a hash value.
Calling Context:
Called by collection classes to generate a hash value.
Parameters:
Return Value:
The hash value.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.