Class: TMIDISequence

Declaration: MIDISequence.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMediaSequence

Inherited By:

TStandardMIDIFile

Purpose:

Collects the tracks of a MIDI sequence. Establishes a contract between a MIDI sequence and TMIDIPlayer. Provides a flexible owning container for the in-memory representation of MIDI sequences. The time stamps in a sequence can refer to metrical, SMPTE, or real-time according to their time format. Most importantly, the inherited member functions of TPlayer always use real-time values, converting automatically to and from the inherent format if needed. A sequence always has a tempo track but it can be empty. Tempo is used, however, only for format kMetrical. Formats of SMPTE use a fixed number of frames per second.

Instantiation:

Allocate on the heap or the stack. Normally allocated on the heap so that a TMIDIPlayer can adopt the sequence.

Deriving Classes:

Override to provide specific backing storage. For example, TStandardMIDIFile reads and writes standard MIDI files and converts between that format and the in-memory representation required by TMIDIPlayer.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements. Owns all contained TMIDITrack objects.

Member Function: TMIDISequence::TMIDISequence

TMIDISequence ()
TMIDISequence (const TMIDISequence &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and to create an empty sequence.
Call this function directly.

Parameters:

Takes no parameters.
const TMIDISequence & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::operator=

TMIDISequence & operator =(const TMIDISequence &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function directly.

Parameters:

const TMIDISequence & -The source object for the assignment.

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: TMIDISequence::~TMIDISequence

virtual ~ TMIDISequence ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

A derived class destructor can write a sequence to persistent storage.

Member Function: TMIDISequence::CreatePreferredTypeList

virtual void CreatePreferredTypeList (TSequenceOf<TMediaType> &) const

Interface Category:

API.

Purpose:

Creates a list of preferred TMIDITypes. Adds to the existing list if it was initially non-empty.

Calling Context:

Call this function directly.

Parameters:

TSequenceOf<TMediaType> & -Assigned preferred type objects.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::ChoosePreferredType

virtual TMediaType * ChoosePreferredType (const TSequenceOf<TMediaType> &) const

Interface Category:

API.

Purpose:

Chooses a preferred type from a list.

Calling Context:

Call this function directly.

Parameters:

const TSequenceOf<TMediaType> & -The input list of TMIDITypes.

Return Value:

The preferred TMIDIType object or NIL if none chosen.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::GetDuration

virtual void GetDuration (TTime &) const

Interface Category:

API.

Purpose:

Gets the duration of the sequence in real time, converting from the inherent format if needed.

Calling Context:

Call this function directly.

Parameters:

TTime & -Assigned the duration in real time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::GetDurationInTicks

virtual void GetDurationInTicks (TMIDITick &) const

Interface Category:

API.

Purpose:

Gets the duration in units of the inherent time format (real time, metrical, or SMPTE time).

Calling Context:

Call this function directly.

Parameters:

TMIDITick & -Assigned the duration.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::CreateSubrange

virtual TMediaSequence * CreateSubrange (const TMediaRange &) const

Interface Category:

API.

Purpose:

Creates a new sequence of the given range. It will have the same number of tracks as the original, even if some tracks do not fall within the range (these will be empty).

Calling Context:

Call this function directly.

Parameters:

const TMediaRange & -The range.

Return Value:

The new sequence object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::IsReadOnly

virtual bool IsReadOnly () const

Interface Category:

API.

Purpose:

Queries whether the sequence can be modified.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the sequence is read-only, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::GetTimeFormat

virtual ETimeFormat GetTimeFormat () const

Interface Category:

API.

Purpose:

Gets the time format of the time stamps in the sequence. These can be any value specified by ETimeFormat.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The time format.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::SetTimeFormat

virtual void SetTimeFormat (ETimeFormat)

Interface Category:

API.

Purpose:

Sets the time format of the time stamps in the sequence.

Calling Context:

Call this function directly.

Parameters:

ETimeFormat -The time format.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Keep in mind that changing the time format does not alter the time stamps of the sequence. It only changes the way they are interpreted.

Member Function: TMIDISequence::GetResolution

virtual Resolution GetResolution () const

Interface Category:

API.

Purpose:

Gets the resolution. A format of kMetrical uses ticks per quarter note, all of the SMPTE formats uses ticks per frame, and kReal ignores this parameter.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The resolution.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::SetResolution

virtual void SetResolution (Resolution)

Interface Category:

API.

Purpose:

Sets the resolution. A format of kMetrical uses ticks per quarter note, all of the SMPTE formats uses ticks per frame, and kReal ignores this parameter.

Calling Context:

Call this function directly.

Parameters:

Resolution -The value in terms of the time format.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Keep in mind that changing the resolution does not alter the time stamps of the sequence. It only changes the way they are interpreted.

Member Function: TMIDISequence::GetTempoTrack

virtual const TMIDITrack * GetTempoTrack () const

Interface Category:

API.

Purpose:

Gets read-only access to the tempo track.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A const pointer to the the tempo track. The lifetime ends with the sequence.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::SetTempoTrack

virtual void SetTempoTrack (const TMIDITrack &)

Interface Category:

API.

Purpose:

Replaces the current tempo track with a new one. A tempo track should only have tempo events in it, and it should have at least one tempo event.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & -The new tempo track.

Return Value:

None.

Exceptions:

Throws TMIDIException::kInvalidTempoTrack if no tempo events are in the track.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::CreateTempoIterator

virtual TSequenceOfIterator < TMIDIPacket > * CreateTempoIterator () const

Interface Category:

API.

Purpose:

Iterates over the TMIDIPacket tempo objects in the sequence.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to an allocated iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::ConvertTickTimeToRealTime

virtual void ConvertTickTimeToRealTime (const TMIDITick & metrical, TTime & realTime) const

Interface Category:

API.

Purpose:

Converts a metrical time to a real time using the tempo track.

Calling Context:

Call this function directly.

Parameters:

TMIDITick metrical -The metrical time.
TTime & realTime -Assigned the converted real time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::ConvertRealTimeToTickTime

virtual void ConvertRealTimeToTickTime (const TTime & realTime, TMIDITick & metrical) const

Interface Category:

API.

Purpose:

Converts a real-time value to a tick-time value.

Calling Context:

Call this function directly.

Parameters:

const TTime & realTime -The real-time value.
TMIDITick & metrical -The tick-time value.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::CreateSequenceIterator

virtual TSequenceOfIterator < TMIDITrack > * CreateSequenceIterator () const

Interface Category:

API.

Purpose:

Iterates over the TMIDITrack objects in the sequence.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to an allocated iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::AdoptAfter

virtual void AdoptAfter (const TMIDITrack & existing, TMIDITrack *)

Interface Category:

API.

Purpose:

Adopts a new track after an existing track.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & existing -The existing track.
TMIDITrack * -The track to adopt.

Return Value:

None.

Exceptions:

Throws TMIDIException::kTrackNotFound if the track is not in the sequence.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::AdoptBefore

virtual void AdoptBefore (const TMIDITrack & existing, TMIDITrack *)

Interface Category:

API.

Purpose:

Adopts a new track after an existing track.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & existing -The existing track.
TMIDITrack * -The track to adopt.

Return Value:

None.

Exceptions:

Throws TMIDIException::kTrackNotFound if the track is not in the sequence.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::AdoptLast

virtual void AdoptLast (TMIDITrack *)

Interface Category:

API.

Purpose:

Adopts a new track as the last track.

Calling Context:

Call this function directly.

Parameters:

TMIDITrack * -The track to adopt.

Return Value:

None.

Exceptions:

Throws TMIDIException::kInvalidTrack if the track is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::AdoptFirst

virtual void AdoptFirst (TMIDITrack *)

Interface Category:

API.

Purpose:

Adopts a new track as the first track.

Calling Context:

Call this function directly.

Parameters:

TMIDITrack * -The track to adopt.

Return Value:

None.

Exceptions:

Throws TMIDIException::kInvalidTrack if the track is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::Orphan

virtual void Orphan (const TMIDITrack &)

Interface Category:

API.

Purpose:

Orphans a track from the sequence.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & -The track to orphan.

Return Value:

None.

Exceptions:

Throws TMIDIException::kTrackNotFound if the track is not in the sequence.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::OrphanAll

virtual void OrphanAll ()

Interface Category:

API.

Purpose:

Orphans all tracks in sequence.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::Count

virtual long Count () const

Interface Category:

API.

Purpose:

Returns the number of tracks, excluding the tempo track.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The count.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::Member

virtual TMIDITrack * Member (const TMIDITrack &) const

Interface Category:

API.

Purpose:

Determines if a track is contained by the sequence.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & -The track to look for.

Return Value:

A pointer to the track if found or NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::After

virtual TMIDITrack * After (const TMIDITrack &) const

Interface Category:

API.

Purpose:

Accesses the track after a given track.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & -The reference track.

Return Value:

A pointer to the track after or NIL if the reference track is the last.

Exceptions:

Throws TMIDIException::kTrackNotFound if the track is not in the sequence.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::Before

virtual TMIDITrack * Before (const TMIDITrack &) const

Interface Category:

API.

Purpose:

Accesses the track before a given track.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & -The reference track.

Return Value:

A pointer to the track before or NIL if the reference track is the first.

Exceptions:

Throws TMIDIException::kTrackNotFound if the track is not in the sequence.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::Last

virtual TMIDITrack * Last () const

Interface Category:

API.

Purpose:

Accesses the last track in a sequence. The tempo track does not count.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the last track or NIL if no tracks.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::First

virtual TMIDITrack * First () const

Interface Category:

API.

Purpose:

Accesses the first track in a sequence. The tempo track does not count.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the first track or NIL if no tracks.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Determines a hash value for collections.

Calling Context:

Called by collections.

Parameters:

Takes no parameters.

Return Value:

The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::IsEqual

virtual bool IsEqual (const MCollectible *) const

Interface Category:

API.

Purpose:

Determines if this is equal to another object.

Calling Context:

Called by collections and directly.

Parameters:

const MCollectible * -The MCollectible to be compared.

Return Value:

Returns true if the tracks and other states are all equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call this function directly.

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: TMIDISequence::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call this function directly.

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.

Member Function: TMIDISequence::ConvertToRealTimeWithTempoTrack

virtual void ConvertToRealTimeWithTempoTrack (const TMIDITick &, TTime &) const

Interface Category:

API.

Purpose:

Converts from tick time to real time using the tempo track.

Calling Context:

Called by a derived class when converting between time domains.

Parameters:

const TMIDITick & -The tick time.
TTime & -The real time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::ConvertFromRealTimeWithTempoTrack

virtual void ConvertFromRealTimeWithTempoTrack (const TTime &, TMIDITick &) const

Interface Category:

API.

Purpose:

Uses the tempo track to convert real time to tick time.

Calling Context:

Called by a derived class to convert between time domains.

Parameters:

const TTime & -The real time.
TMIDITick & -The tick time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::CreateTempoTrackFromFirstTrack

virtual void CreateTempoTrackFromFirstTrack ()

Interface Category:

API.

Purpose:

Extracts tempo events from the first track to the tempo track.

Calling Context:

Called by a derived class to convert from a file format to this format.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::CreateDefaultTempoTrack

virtual void CreateDefaultTempoTrack ()

Interface Category:

API.

Purpose:

Creates a default tempo track.

Calling Context:

Called by a derived class to initialize a sequence.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMIDISequence::SetReadOnly

virtual void SetReadOnly (bool)

Interface Category:

API.

Purpose:

Establishes the sequence as not modifiable.

Calling Context:

Called by a derived class.

Parameters:

bool -true for read-only, false otherwise.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Needs a debugging window.

Click the icon to mail questions or corrections about this material to Taligent personnel.