mvIntro(3dm)mvIntro(3dm)NAMEmvIntro - introduction to the Movie Libraries
SYNOPSIS (Movie File Library)
#include <dmedia/moviefile.h>
-lmoviefile
SYNOPSIS (Movie Playback Library)
#include <dmedia/movieplay.h>
-lmoviefile -lmovieplay
DESCRIPTION
The Silicon Graphics Movie File Library is an application programming
interface that enables you to read, write, and edit movies. A digital
movie is a collection of animated images or digitized video streams,
stored together with an optional audio sound-track. The Silicon Graphics
Movie Playback Library provides a high-level programming interface that
allows you to integrate digital movie playback into an application. The
library supports playback to the graphics screen as well as video output
jacks. Both libraries are provided as DSOs.
The following formats are supported in the Movie File Library and Movie
Playback Library:
SGI versions 1, 2 and 3 (supported compression formats: uncompressed,
MVC1, MVC2, JPEG, RLE8, RLE24, RLE32)
Apple QuickTime(tm) (supported compression formats: uncompressed,
Cinepak(tm), Indeo(tm) 3.2, Apple Video, Apple Animation, JPEG, MJPEGA,
DV, DVCPro, BMP, Planar RGB). Apple QuickTime(tm) reading of compressed
headers are supported. Uncompressed audio data in both unsigned and
twos-comp, as well as 32-bit and 64-bit floating point formats are
supported. The DVC/DVCPro-Audio codec is supported for compression.
IMA4:1 compressed audio data is also supported for reading/decoding only.
(Encoding compressed audio data is not currently supported in the Movie
File Library, except when using mvExportFlattenedFile(3dm) to generate a
new DIF stream.)
Microsoft AVI (Audio Video Interleaved) - (supported compression formats:
Cinepak(tm), Indeo(tm) 3.2, JPEG, Microsoft RLE, Huffman YUV,
uncompressed)
MPEG1 (ISO 11172) - read, play, and append only
Raw DV/DVCPro DIF files - read, play, and export only (including
compressed DV Audio).
Page 1
mvIntro(3dm)mvIntro(3dm)
The Movie File Library provides access to the data stored in a movie
file, allows you to perform lossless editing of a movie, and converts
between movie formats.
In order to develop applications using the Movie Playback Library, you
should be familiar with X Window System programming, as well as the
OpenGL graphics library. The Movie Playback Library can be used with
Xlib, Xt, OSF/Motif, and/or ViewKit. In particular, you should know
about the calls for creating windows and handling window system events.
It is also helpful to be familiar with the IRIS Audio Library. Finally,
if you are creating or converting movies, you should be familiar with the
options for compression and decompression provided by the IRIS
Compression Library and the Digital Media library.
MOVIE and TRACK INSTANCES
The Movie Libraries are organized around the concept of a movie
"instance". Each movie instance contains the state information
associated with a single movie, and is identified by a movie ID similar
in nature to a file descriptor. An application may create several movie
instances at once. To create a movie instance, use the mvOpenFile(3dm),
mvOpenFD(3dm), mvOpenMem(3dm), or mvCreateFile(3dm), mvCreateFD(3dm),
mvCreateMem(3dm) calls. Movie data can be written to a file through
mvWrite, and a movie instance can be destroyed with mvDestroyMovie(3dm).
mvClose is a convenience function that will write and then destroy the
movie instance.
The contents of movies are organized into tracks. Like movies, tracks
are identified by opaque handles or IDs. The type of data contained in a
track is called the track's medium. Currently the Movie Libraries
support DM_IMAGE and DM_AUDIO media. New tracks can be added to a movie
instance by calling mvAddTrack(3dm). Current tracks can be located with
the mvFindTrackByMedium(3dm) or mvFindTrackByIndex(3dm) calls. To remove
a track, call mvRemoveTrack(3dm).
MOVIE PROPERTIES
While movie data is stored in tracks, there are a few properties that are
available on a per-movie basis. For example, mvGetMovieDuration queries
for the overall length of the movie. Additionally, there are functions
that control how the movie is rendered or played back (see
mvGetMovieRect), functions to obtain information about the file (see
mvGetFileFormat), and functions to store and retrieve additional
information about how to preview a file (eg, mvGetMoviePreviewTime), and
textual information associated with a file (e.g. mvGetTitle).
Some of these properties can be stored as part of the DMparams passed
into the movie library using mvCreateMovie(3dm). These parameters are:
MV_FILE_FORMAT, MV_LOOP_LIMIT, MV_LOOP_MODE. Others are set using their
own function, e.g. mvSetMovieRect(3dm), mvSetMovieCurrentTime(3dm). See
Page 2
mvIntro(3dm)mvIntro(3dm)
individual page for details.
Some movie properties can only be stored in certain file formats. For
example, mvSetMoviePlayVolume will be valid while an SGI movie instance
is open, but will not be stored to the movie file when the movie instance
is closed, and hence will not be restored when the file is opened. By
contrast, the movie volume stored in the QuickTime file format will be
restored when the movie file is reopened. For more information about
which movie properties are stored with which file formats see the
individual man pages.
TRACK PROPERTIES
Besides its medium, a track has several other properties that control how
the track is rendered or played back (see mvGetTrackEnable), that
describe the length of the track and position of the track within the
movie (see mvGetTrackOffset).
As with movie properties, some of the track properties can be initialized
when mvAddTrack(3dm) is called. Others need to be set with individual
parameters. See individual man pages for details.
Also, some track properties can only be stored in some of the supported
file formats. See individual man pages for more information about what
track properties are stored with which file formats.
TRACK DATA ORGANIZATION
Track data can be accessed by its playback order or data order. The
playback order is expressed in time, and the data order is expressed by
data index. Each chunk of track data is described by a set of
parameters. In the earlier versions of the Movie Libraries, only one set
of data parameters per track was supported. For example, all images in a
track were described by the same set of params (which can be retrieved by
calling mvGetParams(3dm) on a track). The Movie Libraries, now allow an
application to associate a set of parameters with the set of data chunks
in a track. Refer to the man pages that describe
mvGetTrackDataIndexAtTime(3dm), mvGetTrackDataNumIndex(3dm),
mvGetTrackDataInfo(3dm), mvReadTrackData(3dm), and mvInsertTrackData(3dm)
for more details. To access or edit the track by playback order, see
mvInsertFramesAtTime(3dm), mvDeleteFramesAtTime(3dm),
mvCopyFramesAtTime(3dm), and mvReadFrames(3dm).
TRACK PLAYBACK PROPERTIES
Multiple tracks of the same medium are supported by the Movie Libraries.
To allow the application to coordinate playback of multiple tracks, a
number of functions are provided. For example, each track has a matrix
associated with it that describes its relative orientation to other
tracks (see mvGetTrackMatrix(3dm)). Each track also has a volume
associated with it that, when applicable, scales the volume with respect
Page 3
mvIntro(3dm)mvIntro(3dm)
to other tracks (see mvGetTrackPlayVolume(3dm)). Each track also has a
``layer'' associated with it. This number controls the order in which
the tracks are rendered (see mvGetTrackLayer(3dm)).
RENDERING
In order to simplify the presentation of multiple tracks of the same
medium, we provide a few functions to render the movie (all tracks
blended together) to a current GL context (mvRenderMovieToOpenGL(3dm)),
an image buffer (mvRenderMovieToImageBuffer(3dm)) or an audio buffer
(mvRenderMovieToAudioBuffer(3dm)). These functions take into account the
playback properties as described above when rendering.
FRAME, TIME and TIMESCALE
The Movie Libraries offer two paradigms to accessing movie data.
The frame-based access of data is as if you were indexing the data
directly. It is dependent on the frame rate of the track being accessed.
mvGetTrackLength(3dm) returns the number of frames that can be indexed in
a track. For movies with varying duration frames (see later discussion
on time-based access for details on duration), the number of frames in a
track is calculated by multiplying the frame rate by the duration (in
seconds) of the track. See mvReadFrames(3dm), mvInsertFrames(3dm),
mvDeleteFrames(3dm) and mvPasteFrames(3dm).
The Movie Libraries also provide access to data using a time-based
metaphor that allows users to edit tracks or movies in a granularity
suitable for the application. The Movie Libraries expresse time as a
pair of values--a number of time units, in MVtime, and the number of time
units per second, in MVtimescale. It is important to keep in mind that an
MVtime by itself is meaningless, because MVtime does not have an inherent
unit of measure. An MVtime's MVtimescale must be known in order to
interpret the time.
A simple way to understand time and timescale is to remember that
MVtime/MVtimescale = seconds.
Many of the Movie Libraries' editing functions take a time and/or a
duration and many functions that take both a time and a duration use the
same timescale for both time and duration. By allowing the user to
choose a time/timescale pair, instead of the library choosing a
timescale, these functions allow users to edit tracks or movies in a
granularity suitable for the application. For example, an application
that wants to edit a movie with audio-frame accuracy can use a timescale
that is as fine as the audio sampling rate (e.g. 44100), while an
application that wants to edit everything on 1/30 second boundaries can
Page 4
mvIntro(3dm)mvIntro(3dm)
use a timescale of 30. In fact, the same application can even supply
different timescales for different operations. In order to get equivalent
frame-based editing effects, one could use the time-based editing
functions with the time scale set to an integral multiple of the frame
rate.
For time editing functions, see mvInsertFramesAtTime(3dm),
mvDeleteFramesAtTime(3dm), mvInsertTrackGapAtTime(3dm),
mvCopyFramesAtTime(3dm), mvGetTrackDuration(3dm),
mvGetTrackTimeScale(3dm), etc.
FRAME-BASED vs. TIME-BASED EDITING
Below is a list of the the frame-based routines and their analogs in the
time-based metaphor.
mvReadFrames(3dm)mvRenderMovieToImageBuffer(3dm)mvRenderMovieToAudioBuffer(3dm)mvInsertFrames(3dm)mvInsertFramesAtTime(3dm)mvDeleteFrames(3dm)mvDeleteFramesAtTime(3dm)mvPasteFrames(3dm)mvCopyFramesAtTime(3dm)
To maintain backwards compatibility with previous releases,
the Movie Libraries continue to provides frame-based editing
functions, such as mvReadFrames(3dm) and mvInsertFrames(3dm).
The access provided by these routines is a subset of the functionality
provided by the time-based editing routines described above.
These routines treat a track's data as if they are all formatted in
a uniform way. That is, the track is assumed to have a constant
frame-rate and each frame is assumed to be stored using the same format.
PLAYBACK LIBRARY
The Movie Playback Library uses separate threads of execution to play
movies so that the main application code need not perform any special
actions to maintain movie playback. The Movie Libraries provide an event
queue to notify applications of interesting events like, for example,
that a frame has played or a movie has stopped.
Movies can be set up to play back by calling mvBindOpenGLWindow(3dm).
This will associate a movie with a window on the screen to which the
movie can be played back. Movies can also be played to video output
jacks. (See mvOpenPort(3dm) and mvBindMovieToPorts(3dm)). You may play
more than one movie simultaneously. Once a movie has been successfully
bound to a window, the playback control routines (e.g., mvPlay(3dm) and
mvStop(3dm)) can be used to control the movie's playback state. Movies
can be dis-associated with a window by calling mvUnbindOpenGLWindow(3dm).
Page 5
mvIntro(3dm)mvIntro(3dm)REALTIME JPEG PLAYBACK
The Movie Playback Library is optimized to playback JPEG movies in
realtime when hardware decompression support is available. The list of
supported systems for realtime JPEG playback is:
System Output
O2 graphics, video, both
Octane
with OctaneVideo and OctaneCompression video or both
The Output column specifies the supports output devices for realtime
playback. For O2, realtime playback may be to either the graphics screen
the video output jack or both simultaneously. For all other systems, only
the video output jack or simultaneous video and graphics are supported.
The O2 and Octane both support realtime playback of JPEG and QuickTime MJPEGA.
In order to guarantee realtime playback through the Movie Playback
Library, an application must have the POSIX CAP_SCHED_MGT capability. To
give an application, CAP_SCHED_MGT capabilities, you can do (as root)
# chcap my_application CAP_SCHED_MGT+eip
See chcap(1), capabilities(1), and capability(1) for details.
BACKWARDS COMPATIBILITY WITH PREVIOUS VERSIONS
Silicon Graphics continues to provide support for previous versions of
the Movie Libraries. Previous versions required applications to link
against libmovieGL.a for OpenGL support or libmovie.a for IrisGL support.
The current libraries do not require such a differentiation. For
backwards compatibility, we provide two stub libraries, libmovie.so and
libmovieGL.so, which contain no code. They simply export libmoviefile
and libmovieplay. Applications developed against earlier versions of the
Movie Libraries may continue to link against these stubs. Application
developers that plan on using new features of the movie library should
move their applications away from the obsolete Iris GL calls provided in
previous versions. See the summary below for obsoleted calls and their
replacements.
Previous calls for enabling and disabling the "frame display" have also
been replaced and several frame-based calls to the Movie Playback Library
have been replaced by time-based versions.
Obsolete Calls New Calls
mvBindWindow(3dm)mvBindOpenGLWindow(3dm)mvUnbindWindow(3dm)mvUnbindOpenGLWindow(3dm)
Page 6
mvIntro(3dm)mvIntro(3dm)mvResizeWindow(3dm)mvResizeOpenGLWindow(3dm)mvGrabIrisGL(3dm)mvGrabOpenGL(3dm)mvReleaseIrisGL(3dm)mvReleaseOpenGL(3dm)mvSetFrameDisplay(3dm)mvSetEnableVideo(3dm)mvGetFrameDisplay(3dm)mvGetEnableVideo(3dm)mvShowCurrentFrame(3dm)mvShowCurrentTime(3dm)mvSetCurrentFrame(3dm)mvSetCurrentTime(3dm)mvSetStartFrame(3dm)mvSetStartTime(3dm)mvSetEndFrame(3dm)mvSetEndTime(3dm)
Also the Movie Playback Library no longer sends MV_EVENT_SLOW_PLAY
events. You're application should look for MV_EVENT_WARNING events
with warnings of FRAME_SKIPPED and/or FRAME_REPEATED errors.
See mvEvent(3dm) for details.
This obsoletes the use of mvSetSlowThreshold(3dm) and
mvGetSlowThreshold(3dm).
DEBUGGING
Debugging versions of the Movie Libraries are included in the developer's
release to help you with your application development. To use them, add
/usr/lib/debug to your LD_LIBRARY_PATH and/or /usr/lib32/debug to your
LD_LIBRARYN32_PATH. It provides extensive internal error checking via
assertions. If a problem is detected (for example, an attempt to
reference data past the end of the movie file) the application will abort
with a descriptive message. The final version of your application should
use the non-debug version of the library since use of the debug version
carries a size and performance penalty.
NOTES
QuickTime is a registered trademark of Apple Computer, Inc. Indeo is a
trademark of Intel Corporation. Cinepak is a trademark of Radius, Inc.
OSF/Motif is a trademark of the Open Software Foundation, Inc.
MULTI-THREADED PROGRAMMING WITH THE MOVIE PLAYBACK
The current version of the Movie Playback Library can not be used in
conjunction with the POSIX pthread_create(3P) call for creating threads.
If you need to do multi-threaded programming with the movie library, you
must use sproc(2).
The current versions of the Movie Libraries are not "thread-safe".
FILES
/usr/include/dmedia/moviefile.h
/usr/include/dmedia/movieplay.h
/usr/{lib,lib32}/libmoviefile.so - File
Page 7
mvIntro(3dm)mvIntro(3dm)
/usr/{lib,lib32}/libmovieplay.so - Playback
/usr/{lib,lib32}/debug/libmoviefile.so - File (debug version)
/usr/{lib,lib32}/debug/libmovieplay.so - Playback (debug version)
/usr/{lib,lib32}/libmovie.so - Backwards compatibility stub
/usr/{lib,lib32}/libmovieGL.so - Backwards compatibility stub
/usr/{lib,lib32}/dmedia/movie - Directory with support DSOs
/usr/share/src/dmedia/movie - Example source
SEE ALSOalIntro(3dm), afIntro(3dm), clIntro(3dm), dmedia(3dm).
IRIS Media Libraries Programming Guide
ViewKit Programmer's Guide
The X Window System, DEC Press, Bob Sheifler and Jim Gettys
The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
The OSF/Motif Programmers Reference, Prentice Hall, OSF
Page 8
