mvIntro(3dm) mvIntro(3dm) NAME mvIntro - 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). 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 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 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 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). 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) 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 /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 ALSO alIntro(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