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.
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 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 ALSOalGetFrameNumber(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
