class Transport

Manager of transport facilities. More...

List of all Methods
Full name	`TSE3::Transport`
Definition	`#include <Transport.h>`
Inherits	TSE3::Listener [public ], TSE3::Listener [public ], TSE3::Listener [public ], TSE3::Listener [public ], TSE3::Listener [public ], TSE3::Notifier [public ]


	Annotated List
	Files
	Globals
	Hierarchy
	Index

Public Types

enum TransportMode { Resting, Playing, Recording, SynchroPlaying, SynchroRecording }

Public Methods

Transport (Metronome *metronome, MidiScheduler *scheduler)
virtual ~Transport ()
void attachCallback (TransportCallback *c)
void detachCallback (TransportCallback *c)
MidiScheduler * scheduler () const
MidiFilter * filter ()
Panic * startPanic ()
Panic * endPanic ()
MidiMapper * midiMapper ()
MidiEcho * midiEcho ()
void setFlagTrack (FlagTrack *f)
bool synchro () const
void setSynchro (bool s)
bool punchIn () const
void setPunchIn (bool p)
bool autoStop () const
void setAutoStop (bool s)
Clock playLeadIn () const
void setPlayLeadIn (Clock c)
Clock recordLeadIn () const
void setRecordLeadIn (Clock c)
void play (Playable *p, Clock startTime)
void record (Playable *p, Clock startTime, PhraseEdit *pe, MidiFilter *filter = 0)
void stop ()
void ff (bool strong)
void ffFlag ()
void rew (bool strong)
void rewFlag ()
void poll ()
int status () const
Playable * playable () const
Clock lookAhead () const
void setLookAhead (Clock c)
Clock minimumLookAhead () const
bool adaptiveLookAhead () const
void setAdaptiveLookAhead (bool ala)
int breakUps () const
void inject (MidiCommand c)

Detailed Description

This object handles the playback/record mechanism. It is the central control for musical input and output.

It usually plays a Song, but isn't restricted to Songs since it uses the abstract Playable interface as the music source.

When using this class it is important to call the poll method as often as possible: it does most of the work. It would be a good idea to do this polling in a background thread (see Impl::Mutex for information on threading issues).

Facilities provided by the Transport class include:

Play
Record into PhraseEdit
Fast forward and rewind
Ability to attach callbacks which are kept informed of MIDI activity coming into or leaving the Transport object
Uses Panic objects (for start and stop reset sequences), a MidiEcho object
Synchro start (playback starts when MIDI input recieved)
Uses a FlagTrack to move around the Playable easily
Auto stop at the end of the Playable object
Lead in values for play and record
Adaptive look ahead
Ability to 'inject' a MidiCommand into the Transport stream.

See also: Song, Playable, TransportCallback

Transport (Metronome *metronome, MidiScheduler *scheduler)

Transport

The Transport object starts up in resting mode.

It is presumed that neither the metronome or scheduler objects will be deleted whilst the Transport object exists.

Parameters:

metronome Metronome object to use

scheduler MidiScheduler object to use

See also: status

~Transport ()

~Transport

[virtual]

void attachCallback (TransportCallback *c)

attachCallback

Parameters:

c TransportCallback object to attach

void detachCallback (TransportCallback *c)

detachCallback

Detach a callback object.

Parameters:

c TransportCallback object to detach

MidiScheduler * scheduler ()

scheduler

[const]

Returns the MidiScheduler that this Transport object is using.

Returns: MidiScheduler in use

MidiFilter * filter ()

filter

MidiFilter that affects how all MidiEvents are sent from the Transport object. You can use this to set global overrides for some Song setup; for example to for every MidiEvent to a specific port.

Returns: The Part's MidiFilter object

Panic * startPanic ()

startPanic

The Panic object used to send reset data at transport start.

Returns: Transport's start Panic object

Panic * endPanic ()

endPanic

The Panic object used to send reset data at transport end.

Returns: Transport's end Panic object

MidiMapper * midiMapper ()

midiMapper

This MidiMapper object used to alter output destination.

Returns: Transport's MidiMapper object

MidiEcho * midiEcho ()

midiEcho

Returns the MidiEcho object used to provide soft MIDI Thru.

Returns: Transport's MidiEcho object

void setFlagTrack (FlagTrack *f)

setFlagTrack

Set the FlagTrack. You can specify the value 0 for no FlagTrack. The FlagTrack should be set if your playable object is a Song. If it is not, it's best to reset the FlagTrack value to 0.

This is used when transport is resting and stop is called to snap the stop position to a Flag position.

Parameters:

f FlagTrack to use - it should tally with the current Song

bool synchro ()

synchro

[const]

Returns the current synchro mode.

When enabled, transport will not start immediately when play/record is called: it will only start when MIDI input is recieved from the scheduler.

Returns: Synchro mode status

See also: setSynchro

void setSynchro (bool s)

setSynchro

Set the synchro status.

Parameters:

s New synchro mode status

See also: synchro

bool punchIn ()

punchIn

[const]

Returns the currrent punch-in record status.

This effects how the recording is handled. When disabled, record will mute the record channel. When enabled, muting only occurs when the first MIDI input is recieved.

Returns: Punch in status

See also: setPunchIn

void setPunchIn (bool p)

setPunchIn

Set the punch-in record status.

Parameters:

p New punch in status

See also: punchIn

bool autoStop ()

autoStop

[const]

Returns the currrent auto stop status.

When enabled playback will automatically stop at the end of the Playable object. This will not occur in recording mode.

Returns: Auto stop mode status

See also: setAutoStop

void setAutoStop (bool s)

setAutoStop

Set the auto stop status.

Parameters:

s New auto stop mode status

See also: setAutoStop

Clock playLeadIn ()

playLeadIn

[const]

Returns the playback lead in, the number of PPQN before Song playback begins.

Returns: The playback lead in

See also: setPlaybackLeadIn

void setPlayLeadIn (Clock c)

setPlayLeadIn

Sets the value of the playback lead in.

Parameters:

c New playback lead in

See also: playbackLeadIn

Clock recordLeadIn ()

recordLeadIn

[const]

Returns the record lead in, the number of PPQN before Song recording begins.

Returns: The record lead in

See also: setRecordLeadIn

void setRecordLeadIn (Clock c)

setRecordLeadIn

Sets the value of the record lead in.

Parameters:

c New record lead in

See also: recordLeadIn

void play (Playable *p, Clock startTime)

play

Call this to start playback.

If the request is successful, an event will be returned to all TransportListeners.

Parameters:

p The object to play.

startTime The time to start playback from.

void record (Playable *p, Clock startTime, PhraseEdit *pe, MidiFilter *filter = 0)

record

Call this to start recording.

Whilst you are recording, a Playable can be played back (this will normally be the Song you are working on. You can optionally mute a Track (well, it will normally be a Track) by specifying it's MidiFilter. (The 'setStatus' method is used to perform the muting - it will be reset correctly afterwards).

If course, you do not have to perform a mute, or do any playback at all if you so wish.

You would want to specify a mute Track to silence the Track that the user thinks recording is taking place on (when at the moment the Song is not being altered by the Transport's recording process at all).

If the record request is successful, an event will be returned to all TransportListeners. Record may not do anything (for example, you cannot enter Recording mode from Playing mode).

If punch-in mode is enabled, the Track the user thinks recording is being performed on (when it's in fact going into a PhraseEdit object) will be muted when MIDI input is first recieved. This muting is achieved by setting the Track's MidiFilter status to false. It will be restored when stop is called.

If punch-in mode is disabled, then the filter will be muted immediately, and restored when stop is called.

If 0 is passed in filter then no muting will occur.

Parameters:

p The object to play.

startTime The time to start recording from.

pe The PhraseEdit to record into.

filter The filter for punch-in track (or 0).

void stop ()

stop

Stop playback.

If the request is successful, an event will be returned to all TransportListeners.

If in Resting mode, then the 'resting clock' will be moved to time zero.

void ff (bool strong)

ff

Fast forward.

Makes the playback position jump forwards by Clock::PPQN.

Parameters:

strong If true, fast forwards four times faster.

void ffFlag ()

ffFlag

Fast forward to next flag position, if there is one.

void rew (bool strong)

rew

Rewind.

Makes the playback position jump backwards by Clock::PPQN.

Parameters:

strong If true, rewinds four times faster.

void rewFlag ()

rewFlag

Rewind to previous flag position, or the start if there is none.

void poll ()

poll

The Transport object activity poll interface.

This must be called often and rapidly (say every 10 usecs) if you want to handle MIDI input properly. This includes recording and MIDI echo.

If you're only doing playback (and have disabled the MIDI echo facility) then you can afford to call this only as often as you need to (this is dependant on the lookAhead()). This will give your processor quite a rest.

The poll method schedules an amount of musical data for playback via the MidiScheduler. The size of this 'window' of data that is scheduled ahead of time is set by lookAhead().

int status ()

status

[const]

Returns the current state of the Transport object

Returns: Current Transport state

Playable * playable ()

playable

[const]

If status is not Resting, then this will return a pointer to the current Playable object.

When resting, this returns zero.

Returns: Current playable

See also: play, record

enum TransportMode { Resting, Playing, Recording, SynchroPlaying, SynchroRecording }

TransportMode

Transport status definitions for the current mode, as returned by the status method.

Clock lookAhead ()

lookAhead

[const]

Returns the look ahead value. This is the amount of data that the Transport object will schedule ahead of time to ensure smooth and unbroken playback.

Returns: Look ahead value

See also: setLookAhead, minimumLookAhead, adaptiveLookAhead

void setLookAhead (Clock c)

setLookAhead

Sets the look ahead value.

Parameters:

c New look ahead value

See also: lookAhead

Clock minimumLookAhead ()

minimumLookAhead

[const]

Returns the minimum value lookAhead can be set to. (There has to be some kind of limit, setting it to zero is just asking for trouble.)

Returns: Minimum look ahead value

See also: lookAhead, setLookAhead

bool adaptiveLookAhead ()

adaptiveLookAhead

[const]

Returns whether the 'adaptive look ahead' facility is active.

Adaptive look ahead causes the poll method to calculate the best value for lookAhead. The calculation is based on the frequency of calls to poll and aims to reduce the look ahead as much as possible (in order to increase system responsivity) whilst ensuring that it is not so low as to cause playback break-up.

Returns: Adaptive look ahead status

See also: setAdaptiveLookAhead, lookAhead, setLookAhead

void setAdaptiveLookAhead (bool ala)

setAdaptiveLookAhead

Set the value of the adaptive look ahead feature.

Parameters:

ala New adaptive look ahead status

See also: adaptiveLookAhead

int breakUps ()

breakUps

[const]

Returns the number of times playback has 'broken up' during the current run of the Transport object. If this returns true you may wish to increase the value of lookAhead.

Returns: The number of time playback has 'broken up'

See also: lookAhead, setLookAhead

void inject (MidiCommand c)

inject

Injects a MidiCommand into the Transport object. This is a facility used by components such as an on-screen keyboard.

The Transport object acts as if this MidiCommand was recieved from the MidiScheduler object, recording/echoing it.

The side effect of calling this member function is that a call to poll will be made (to process the injected MidiCommand.

Take care: if you inject a MidiCommand_NoteOn you must ballance it with a MidiCommand_NoteOff later on or you will experience 'hanging notes'.

Parameters:

c The MidiCommand to inject

void MidiScheduler_Started (MidiScheduler *)

MidiScheduler_Started

[virtual]

void MidiScheduler_Stopped (MidiScheduler *)

MidiScheduler_Stopped

[virtual]

void MidiScheduler_Moved (MidiScheduler *)

MidiScheduler_Moved

[virtual]

void Notifier_Deleted (FlagTrack *)