mvSync(3dm)                                                        mvSync(3dm)


NAME
     mvPlayAt, mvGetMovieSyncInfo, mvSetMovieSyncInfo - Intra-application
     synchronization support


SYNOPSIS
     #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
     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.


     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 alGetFrameNumber(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
     All three calls return DM_SUCCESS on success and DM_FAILURE on failure.
     See mvGetErrno for details on possible error conditions.


SEE ALSO
     alGetFrameNumber(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)


                                                                        Page 2