Class: TMovie

Declaration: Movie.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TPlayer

Inherited By:

None.

Purpose:

A convenience class for playback of QuickTime movies.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derive to create a specific implementation of TMovie, usually platform dependent.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TMovie::TMovie

TMovie ()
TMovie (TDirectory& directory, const TFileSystemEntityName& fileName, MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead, MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead)
TMovie (const TFileSystemEntity& file, MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead, MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead)
TMovie (const TMovie & aMovie)

Interface Category:

API.

Purpose:

Default constructor.
Normal constructor. Creates a movie file, if necessary, and opens it for playback or recording.
Normal constructor. Opens an existing movie file for playback or recording.
Copy constructor.

Calling Context:

Called by the stream-in operators and directly.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
TDirectory & directory -The directory in which the movie file is located or is to be created.
const TFileSystemEntityName& fileName -The name of the movie file to play or record.
MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead -Specifies owner permissions for the file system. The value must be MOpenFile::kReadWrite for recording.
MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead -Specifies non-owners' permissions for the file system.
const TFileSystemEntity & fileEntity -The entity corresponding to the movie file to play or record.
MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead -Specifies owner permissions for the file system. The value must be MOpenFile::kReadWrite for recording.
MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead -Specifies non-owners' permissions for the file system.
const TMovie & aMovie -The TMovie object to be copied.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kNoSequence if the movie can't be opened.

Concurrency:

Multithread safe.

Other Considerations:

Note: The file system entity parameter used in constructing objects of this class contains an absolute pathname. When streamed, objects will continue to reference a file on the machine of origin.

Member Function: TMovie::~TMovie

virtual ~ TMovie ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetMovieSize

virtual TGPoint GetMovieSize () const

Interface Category:

API.

Purpose:

Gives the size of the video portion of the movie.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TGPoint -The dimensions, in pixels, of the video portion of the movie. Returns the point (0, 0) if there is no video in the movie.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::SetOutputGain

virtual void SetOutputGain (double gain)

Interface Category:

API.

Purpose:

Sets the output gain of the sound track. Used to adjust the playback volume.

Calling Context:

Call this function directly.

Parameters:

double gain -The output gain factor. The signal is multiplied by this number. A value of 1.0 leaves the volume unchanged. Values greater than 1.0 raise the volume, while values between 1.0 and 0.0 reduce the volume. A value of 0.0 yields silence.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetOutputGain

virtual double GetOutputGain () const

Interface Category:

API.

Purpose:

Returns the output gain of the sound track. The output gain adjusts the playback volume.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

double -The input gain factor. The default is 1.0.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::CreateView

virtual TView* CreateView () const

Interface Category:

API.

Purpose:

Creates a view for the movie that can be adopted into the view root.

Calling Context:

The client must call this member function and adopt the resulting view into the view root in order for the video portion of the movie to be displayed.

Parameters:

Takes no parameters.

Return Value:

TView* -The view used to display the video portion of the movie.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::IsSyncable

virtual bool IsSyncable () const

Interface Category:

API.

Purpose:

Specifies whether TMovie implementation supports synchronization.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

bool -true if full API is supported. false if API is only partially supported.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetFileSystemEntity

virtual TFileSystemEntity GetFileSystemEntity () const

Interface Category:

API.

Purpose:

Provides access to the file system entity associated with the movie file, if any.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TFileSystemEntity -The file system entity for the current movie file. If no sequence has been specified, an invalid entity is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetMediaComponentType

virtual const TMediaComponentType& GetMediaComponentType () const

Interface Category:

API.

Purpose:

Called to determine the media type and category of this player. Provides the values of TMediaType::GetMovie for the media type and TMediaComponentType::GetConveniencePlayer for the component category.

Calling Context:

Called by the Media Registry as a key into the component dictionary.

Parameters:

Takes no parameters.

Return Value:

const TMediaComponentType& -The media component type value associated with this player.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::Play

virtual void Play ()

Interface Category:

API.

Purpose:

Starts playback and returns immediately. Playback begins from the current position.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::Stop

virtual void Stop ()

Interface Category:

API.

Purpose:

Stops playback or recording immediately.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::WaitUntilComplete

virtual void WaitUntilComplete ()

Interface Category:

API.

Purpose:

Blocks the calling thread until playback or recording finishes.

Calling Context:

Play and Record return immediately, so call this function to stop all processing in a thread until playback or recording stops.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::IsRecordable

virtual bool IsRecordable () const

Interface Category:

API.

Purpose:

Determines whether the current sequence can be recorded.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the current sequence can be recorded, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::IsPlaying

virtual bool IsPlaying () const

Interface Category:

API.

Purpose:

Determines whether the movie is playing.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the movie is playing, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::IsRecording

virtual bool IsRecording () const

Interface Category:

API.

Purpose:

Determines whether the movie is recording.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the movie is recording, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::AdviseWillPlay

virtual void AdviseWillPlay ()

Interface Category:

API.

Purpose:

Hints to the movie that you are going to call Play soon. Gives the movie a chance to perform time-consuming preparation for playback (such as paging in the first few seconds of a media sequence) in advance of Play being called.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetPreroll

virtual void GetPreroll (TTime & preroll) const

Interface Category:

API.

Purpose:

Returns the worst case delay that occurs before playback starts. The time is relative to the real-time clock.

Calling Context:

If you want to start a movie exactly at time x, do the following: 1) Sync the movie to a clock (see SyncTo). 2) Call GetPreroll to get the preroll time. 3) Call Play at least preroll seconds in advance of time x. The movie will start playing at time x.

Parameters:

TTime & preroll -The preroll time. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetDuration

virtual void GetDuration (TTime & duration) const

Interface Category:

API.

Purpose:

Fills in the TTime with the duration of the movie.

Calling Context:

Call this function directly.

Parameters:

TTime & duration -The duration. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::Seek

virtual void Seek (const TTime & position)

Interface Category:

API.

Purpose:

Sets the current position in the movie.

Calling Context:

Call this function directly.

Parameters:

const TTime & position -The position you want to seek to. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetPosition

virtual void GetPosition (TTime & position) const

Interface Category:

API.

Purpose:

Fills in the TTime with the current position of the movie. Works at all times regardless of whether the movie is stopped, playing, or recording.

Calling Context:

Call this function directly.

Parameters:

TTime & position -The current position. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::GetClock

virtual void GetClock (TSyncableClockSurrogate & internalClock) const

Interface Category:

API.

Purpose:

Returns a clock surrogate that is synced to the movie's internal clock. You can synchronize another clock to this movie using this clock.

Calling Context:

Call this function directly.

Parameters:

TSyncableClockSurrogate & internalClock -The surrogate for the movie's clock.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::SyncTo

virtual void SyncTo (const TSyncableClockSurrogate & externalClock, double rate =1.0, const TTime & offset =TTime :: kZero)

Interface Category:

API.

Purpose:

Causes the movie to be synchronized to the specified clock.

Calling Context:

Call this function directly.

Parameters:

const TSyncableClockSurrogate & externalClock -The master clock to sync to.
double rate =1.0 -The movie will run at this rate relative to the master clock.
const TTime & offset =TTime :: kZero -The movie's clock (and current position) will be at this offset from the master clock's time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::SyncToKeepMyTime

virtual void SyncToKeepMyTime (const TSyncableClockSurrogate & externalClock, double rate =1.0)

Interface Category:

API.

Purpose:

Causes the movie to be synchronized to the specified clock but leaves the movie's current position unchanged.

Calling Context:

Call this function directly.

Parameters:

const TSyncableClockSurrogate & externalClock -The master clock to sync to.
double rate =1.0 -The movie will run at this rate relative to the master clock.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::SyncToSelf

virtual void SyncToSelf ()

Interface Category:

API.

Purpose:

Causes the movie to be synchronized to its own internal clock, as opposed to an external clock. Internal sync is the default behavior of a newly constructed TMovie.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::AdoptSequence

virtual void AdoptSequence (TMediaSequence * data)

Interface Category:

API.

Purpose:

Loads a movie sequence into the movie. The movie now owns the storage for the sequence, so do not delete the sequence unless you get it back by calling OrphanSequence!

Calling Context:

Call this function directly.

Parameters:

TMediaSequence * data -The movie sequence to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::OrphanSequence

virtual TMediaSequence * OrphanSequence ()

Interface Category:

API.

Purpose:

Ejects the media sequence from the movie, returning a pointer to the sequence. The movie no longer owns the storage for the sequence. It is up to the client to delete the sequence.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TMediaSequence* -The media sequence ejected from the movie.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::Record

virtual void Record ()

Interface Category:

API.

Purpose:

Starts recording and returns immediately. Currently unimplemented. Call Stop to stop recording. Call WaitUntilComplete to block until recording is finished. Note that a TMovie is either recording, stopped, or playing. It cannot record and play at the same time.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws kIsNotRecordable if the media sequence in the movie is not recordable.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::AdviseWillRecord

virtual void AdviseWillRecord ()

Interface Category:

API.

Purpose:

Performs time-consuming preparation for recording.

Calling Context:

Only call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::CreateStoppedInterest

virtual TInterest * CreateStoppedInterest ()

Interface Category:

API.

Purpose:

Creates an interest in when the movie stops playing.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TInterest* -The created interest.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::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:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::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:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::operator=

TMovie & operator =(const TMovie &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function directly.

Parameters:

const TMovie & -The object to be assigned to.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns a hash value.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

long -The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMovie::operator==

virtual bool operator ==(const TMovie & other) const

Interface Category:

API.

Purpose:

Compares two objects for equality.

Calling Context:

Call this function directly.

Parameters:

const TMovie & other -The object to compare with.

Return Value:

Returns true if the objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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