*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> movie/mvIntro (3d)              



mvIntro(3dm)							  mvIntro(3dm)

NAME    [Toc]    [Back]

     mvIntro - introduction to the Movie Libraries

SYNOPSIS (Movie	File Library)
     #include <dmedia/moviefile.h>


SYNOPSIS (Movie	Playback Library)
     #include <dmedia/movieplay.h>

	 -lmoviefile -lmovieplay

DESCRIPTION    [Toc]    [Back]

     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.  Currently Apple QuickTime(tm) movies with
     compressed	audio tracks are supported for reading/decoding	of audio data
     compressed	with the IMA4:1	compressed audio codec,	and the	DVC/DVCProAudio
 codec. (Encoding compressed audio data is not currently supported
     in	the movie library, except when using mvExportFlattenedFile(3dm)	to
     generate a	new DIF	stream.)

     Microsoft AVI (Audio Video	Interleaved) - read only (supported
     compression formats: Cinepak(tm), Indeo(tm) 3.2, Microsoft	RLE,

     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.

     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    [Toc]    [Back]

     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    [Toc]    [Back]

     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	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).


     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    [Toc]    [Back]

     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.

     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),
     mvDeleteFramesMVtime,	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

     For time editing functions, see mvInsertFramesAtTime(3dm),
     mvDeleteFramesAtTime(3dm),	mvInsertTrackGapAtTime(3dm),
     mvCopyFramesAtTime(3dm), mvGetTrackDuration(3dm),
     mvGetTrackTimeScale(3dm), etc.

     Below is a	list of	the the	frame-based routines and their analogs in the
     time-based	metaphor.

     mvReadFrames(3dm)		mvRenderMovieToImageBuffer(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    [Toc]    [Back]

     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)


     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
	   with	IndyVideo and CosmoCompress	     video or both
	   or IndyVideo601 and CosmoCompress
	   with	ImpactVideo and	ImpactCompression    video or both
	   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.

     All systems except	the Indy support realtime playback of JPEG and QuickTime MJPEGA.
     Indy (with	IndyVideo and CosmoCompress) does not support 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.

     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

     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.

									Page 6

mvIntro(3dm)							  mvIntro(3dm)

	 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

DEBUGGING    [Toc]    [Back]

     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    [Toc]    [Back]

     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.

     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".

									Page 7

mvIntro(3dm)							  mvIntro(3dm)

FILES    [Toc]    [Back]

     /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    [Toc]    [Back]

     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

									PPPPaaaaggggeeee 8888
[ Back ]
 Similar pages
Name OS Title
mvResizeWindow IRIX Notify Movie Playback Library of window size changes #include #include
mvGrabRelease IRIX provide safe usage of graphics libraries from Movie Playback Library clients
mvOptimize IRIX optimize a movie file for playback after editing operations, or create a flattened movie file
mvShowCurrentFrame IRIX Display current movie frame on screen for a movie instance
makemovie IRIX make a movie from movie, image, and audio files
mvGetErrno IRIX return information for Movie Library error codes
mvEvent IRIX Movie Playback Library event handling functions
mvExportFlattenedFile IRIX export a movie to a given file format
iflMT IRIX a multi-track movie file
mvGetBitrate IRIX get the stored bitrate of a movie file or track
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service