mvGetMoviePreviewTime(3dm)                          mvGetMoviePreviewTime(3dm)


NAME
     mvGetMovieCurrentTime, mvGetMovieGalleryTime, mvGetMoviePreviewTime,
     mvGetMovieSelectionTime, mvSetMovieCurrentTime, mvSetMovieGalleryTime,
     mvSetMoviePreviewTime mvSetMovieSelectionTime - get and set movie times
     for special purposes

SYNOPSIS
     MVtime mvGetMovieCurrentTime( MVid movie, MVtimescale timeScale )
     DMstatus mvSetMovieCurrentTime( MVid movie,
                                     MVtime time, MVtimescale timeScale )
     MVtime mvGetMovieGalleryTime( MVid movie, MVtimescale timeScale )
     DMstatus mvSetMovieGalleryTime( MVid movie,
                                     MVtime time, MVtimescale timeScale )
     DMstatus mvSetMoviePreviewTime( MVid movie,
                                     MVtime time, MVtime duration,
                                     MVtimescale timeScale )
     DMstatus mvGetMoviePreviewTime( MVid movie,
                                     MVtime *time, MVtime *duration,
                                     MVtimescale timeScale )
     DMstatus mvSetMovieSelectionTime( MVid movie,
                                    MVtime time, MVtime duration,
                                    MVtimescale timeScale )
     DMstatus mvGetMovieSelectionTime( MVid movie,
                                    MVtime *time, MVtime *duration,
                                    MVtimescale timeScale )

DESCRIPTION
     These functions allow certain information about a movie's current time,
     selection, still ``gallery,'' or movie ``preview'' to be accessed or
     stored with a movie.

     The movie current time is a time and timescale stored with a movie so
     that the next time the movie is opened, the movie can automatically be
     started at the same location it was at in the previous editing/viewing
     session. mvGetMovieCurrentTime allows the user to query for a movie's
     current time (which will be returned in the timeScale given), and
     mvGetMovieCurrentTime allows the user to set a movie's current time and
     timescale.

     The movie gallery time is a time and timescale stored with a movie on
     disk which point to a good frame to use as a still preview. Since many
     movies begin with a fade-in from black, in many cases, the best frame to
     use for a still gallery shot is not at t = 0, but rather someplace
     shortly after the start of the movie, where there is ``real'' content.
     mvGetMovieGalleryTime allows the user to query for a movie's gallery time
     (which is returned in the timeScale specified by the user), and
     mvSetMovieGalleryTime allows the user to set a movie's gallery time and
     timeScale.

     The movie preview time is a time and duration (in the given timeScale)
     describing a portion of the movie that can be used as a short preview of
     the movie (for example, a representative portion of the movie).


     mvGetMoviePreviewTime allows the preview time and duration to be queried
     (they are both returned in the timeScale specified by the user), and
     mvSetMoviePreviewTime allows the preview time and duration to be set, in
     the timeScale specified by the user.

     The movie selection time is a time and duration (in the given timeScale)
     describing the movie's selection. It may be useful in certain
     applications to store the selection across edit sessions, so that less
     set-up is required the next time the movie is to be edited (although
     applications are not required to implement this functionality).
     mvGetMovieSelectionTime allows the selection time and duration to be
     queried (they are both returned in the timeScale specified by the user),
     and mvSetMovieSelectionTime allows the selection time to be set, in the
     timeScale specified by the user.


RETURN VALUES
     mvGetMovieCurrentTime and mvSetMovieCurrentTime should not be confused
     with mvGetCurrentTime and mvSetCurrentTime.  The former modify a time
     stored in the movie file while the latter affect the playback of the
     movie.

     mvGetMovieCurrentTime and mvGetMovieGalleryTime return -1 on error (e.g.,
     invalid movie, invalid timescale), and a positive time on success.

     The remaining functions return either DM_SUCCESS or DM_FAILURE.


NOTES
     For interoperability with QuickTime(tm):

     When reading/writing a QuickTime file, a movie's Gallery time will be
     read or stored as QuickTime's ``Movie Poster'' time. A movie's current
     time will be read or stored as a QuickTime ``Movie Time.''

     Similarly, a movie Preview will be read or stored as a QuickTime ``Movie
     Preview'' time, and a movie selection will be read or stored as a
     QuickTime ``Movie Selection'' time.

     When writing a QuickTime file, these values will be converted to the
     movie's timescale (see mvGetMovieTimeScale, mvConvertTime).

     These values are not stored in all file formats.

     QuickTime is a registered trademark of Apple Computer, Inc.


See Also
     mvConvertTime(3dm), mvGetMovieTimeScale(3dm), mvGetErrno(3dm).


                                                                        Page 2