mvSync(3dm)							   mvSync(3dm)

NAME    [Toc]    [Back]

     mvPlayAt, mvGetMovieSyncInfo, mvSetMovieSyncInfo -	Intra-application
     synchronization support

SYNOPSIS    [Toc]    [Back]

     #include <dmedia/moviefile.h>
     #include <dmedia/movieplay.h>

     typedef struct
     {
	 long long    ust;
	 MVtime	      movieTime;
	 MVtimescale  timeScale;
     } MVsyncInfo;


     DMstatus mvPlayAt(MVid movieid, MVsyncInfo	*info);

     DMstatus mvGetMovieSyncInfo(MVid movieid, MVsyncInfo *info);

     DMstatus mvSetMovieSyncInfo(MVid movieid, MVsyncInfo *info);

DESCRIPTION    [Toc]    [Back]

     The Movie Playback	Library	playback engine	represents synchronization
     information using the MVsyncInfo structure.  The structure	describes two
     times which are synchronous.  The ust is an Unadjusted System Time	(in
     nanoseconds) and movieTime	(along with its	timeScale) typically
     represents	an instant in a	movie or some other media to which or from
     which one is expressing synchronization.  The way to read an MVsyncInfo
     is	to say that the	given movieTime	will be	displayed, played, or
     presented at the given Unadjusted System Time. Synchronization between
     multiple movies or	devices	or other media can be easily accomplished by
     synchronizing both	sources	to some	Unadjusted System Time.	 For more
     detail on Unadjusted System Time, see dmGetUST(3dm).


     You can use the calls above to slave the Movie Playback Library engine to
     an	external time source.  You can also use	these calls to slave an
     external timer to the Movie Playback Library engine.  The task of
     synchronization can be divided into two problems, initial sync and
     subsequent	clock drift.  To handle	initial	sync, you can use the
     mvPlayAt(3dm) call.  You must provide an MVsyncInfo struct	that contains
     the movie time you	would like the playback	engine to start	and an
     Unadjusted	System Time at which you would like that movie time to be
     presented.	The UST	should be at least MV_MIN_PREROLL_NANOS	nanoseconds in
     the future.  When the UST requested is too	soon for the Movie Playback
     Library engine to attain synchronization, the Movie Playback Library
     engine will send an MV_EVENT_WARNING event	with an	error code of
     MV_UNATTAINABLE_SYNC.




									Page 1






mvSync(3dm)							   mvSync(3dm)



     Because the underlying time source	for the	Movie Playback Library engine
     and your external time source may differ, you may need to update the
     Movie Playback Library engine (if it is the slave)	or your	own time
     source (if	it is the slave).  You can use the mvGetMovieSyncInfo(3dm)
     call to get the Movie Playback Library engine's current synchronization
     information for a movie. (The UST returned	in the struct is guarenteed to
     be	within 2 milliseconds of the current time.)  To	update the slave the
     movie library to your external source, you	should call
     mvSetMovieSyncInfo(3mv) at	least every MV_MIN_SYNC_DISTANCE_NANOS
     nanoseconds to guarentee accurate synchronization.	 Furthermore the UST
     which you provide to mvSetMovieSyncInfo(3mv) must not be too far in the
     future or too far in the past.  If	you provide a UST which	is
     MV_MIN_SYNC_DISTANCE_NANOS	nanoseconds ahead or behind the	Movie Playback
     Library engine, mvSetMovieSyncInfo(3mv) will fail and set the current
     Movie Library error to MV_UNATTAINABLE_SYNC.  Calls to either
     mvSetMovieSyncInfo(3mv) or	mvGetMovieSyncInfo(3dm)	must be	made while the
     movie is playing.	(See mvIsMovieStopped(3dm)).  If the movie is not
     currently playing,	the call will fail and the current Movie Library error
     is	set to MV_OUT_OF_CONTEXT.


     For synchronizing with audio, see ALgetframenum(3dm) and
     ALgetframetime(3dm).  For synchronizing with video	see
     vlGetUSTMSCPair(3dm), vlGetFrontierMSC(3dm), vlGetUSTPerMSC(3dm).	For
     synchronizing with	the graphics screen, see glXGetVideoSyncSGI(3g?).


     An	alternative to using mvGetMovieSyncInfo(3dm) is	to listen and respond
     to	MV_SYNC_EVENT events.  See mvEvent(3dm)	for details on MV_SYNC_EVENT
     events and	Movie Library event processing in general.

RETURN VALUES    [Toc]    [Back]

     All three calls return DM_SUCCESS on success and DM_FAILURE on failure.
     See mvGetErrno for	details	on possible error conditions.

SEE ALSO    [Toc]    [Back]

     ALgetframenum(3dm), ALgetframetime(3dm), glXGetVideoSyncSGI(3dm),
     mvIntro(3dm), mvEvent(3dm), mvGetErrno(3dm), mvGetMovieCurrentTime(3dm),
     mvIsMovieStopped(3dm), mvBindOpenGLWindow(3dm), mvPlay(3dm),
     mvSetPlayEveryFrame(3dm), mvSetPlaySpeed(3dm), mvSetPlaySpeed(3dm),
     vlGetUSTMSCPair(3dm), vlGetFrontierMSC(3dm), vlGetUSTPerMSC(3dm)


									PPPPaaaaggggeeee 2222