mvOpen(3dm)mvOpen(3dm)NAME
mvOpenFile, mvOpenFD, mvOpenMem - open movie instances
SYNOPSIS
#include <dmedia/moviefile.h>
DMstatus mvOpenFile( const char* fileName, int oflag, MVid* returnMovie )
DMstatus mvOpenFD( int fd, MVid* returnMovie )
DMstatus mvOpenMem( void* pointer, size_t size, MVid* returnMovie )
DESCRIPTION
mvOpenFile, mvOpenFD, and mvOpenMem read an existing movie and create a
movie instance in memory that holds information about it. A movie
instance is a handle that allows you to read, write, edit, and play a
movie file. It contains information about the different tracks in a
movie. These operations are defined for three different storage media
(file name, file descriptor, and memory).
mvOpenFile is used to read files on disk. fileName gives the name of the
file to open, and oflag must have either O_RDONLY (for read-only access)
or O_RDWR (for read/write access) masked in. MPEG files may take
additional flags masked into the oflag parameter, to determine whether
the MPEG file should be prescanned or not (MV_MPEG1_PRESCAN_OFF), and to
determine the decimation factor of the audio
(MV_MPEG1_AUDIO_BANDWIDTH_FULL, MV_MPEG1_AUDIO_BANDWIDTH_HALF,
MV_MPEG1_AUDIO_BANDWIDTH_QUARTER).
Note that MPEG files will have a default audio decimation factor of a
quarter. As such the sampling rate will be set to a quarter of its
original value. The full bandwidth flag must be used if audio quality is
to be played at the same quality of its original recording.
Note that in some circumstances, even if a movie is opened O_RDWR, the
Movie File Library may still only be able to perform read accesses on it.
Reasons for this include incomplete support of certain file formats or
lack of necessary compression functionality. mvIsReadOnly(3dm) should be
called after a movie has been opened to determine whether or not actions
which modify the movie will be allowed.
mvOpenFD is used to open a movie from a file descriptor. Using file
descriptors allows movies to be embedded within other files. For
example, a movie file might be embedded in the file of a word-processing
program. When the word processing program is ready to access the movie,
it seeks to the position of the movie within its file and passes the file
descriptor (fd) to the movie library.
mvOpenMem opens a movie of size size at location pointer from memory.
Page 1
mvOpen(3dm)mvOpen(3dm)
mvOpenFile, mvOpenFD, and mvOpenMem all return the identifier for the new
movie in returnMovie. If everything goes well they return DM_SUCCESS,
otherwise DM_FAILURE is returned.
NOTES
Movies consist of two parts: the actual frames (called data), and the
information used to reference those frames (called metadata). In movie
files created by mvCreateFile, both parts are contained in one file, with
the metadata portion usually following the data portion. In movie files
created on a Macintosh, the two parts are contained in separate files
called forks. Data-forks contain the data part of the movie, and
resource-forks contain the metadata. Files containing both parts are
called single-fork movie files.
There are several naming conventions used to associate resource-forks
with their data-fork mates. In one convention, the resource-fork for
data-fork /tmp/movie.mov (for example) is /tmp/.HSResource/movie.mov:
i.e. named identically to the data-fork, residing in a directory called
.HSResource directly under the directory containing the data-fork. In
another convention, the resource-fork for the same data-fork would be
/tmp/%movie.mov--both forks in the same directory, the resource-fork
named by prepending a '%' character to the data-fork name.
On a Mac, resource-forks are considered to be primarily system files, so
their existence is transparent to the user. Therefore, mvOpenFile always
expects data-fork names, never resource-fork names. Given a data-fork
filename, it automatically searches for a resource-fork complying with
either of the above naming conventions, and--if found--uses it during the
opening process. If no resource-fork is found, it assumes the data file
contains a single-fork movie.
Because of this transparent synthesis of the resource-fork name from the
input data-fork name, only mvOpenFile works with dual-fork movie files.
The Movie library provides the ability to create movies that reference
data contained in other movie files (see the byReference parameter of
mvCopyFramesAtTime(3dm)). This means that rather than copying data from
movie B to movie A and creating references in movie A's metadata to the
new data, we can merely create references in movie A's metadata to the
data frames residing in movie B. These references are called external
references, or aliases.
Although this is a very useful capability, the resulting movie file
requires that none of the files whose data it uses be moved, modified, or
destroyed, since the files contain frames needed by the movie. To create
a movie containing no external references from one that does, open an
empty movie file, and use mvOptimize(3dm) to copy the external data into
the new movie's data section. The result will be a self-contained, or
flattened movie.
Note that flattened vs. nonflattened and single- vs. double-fork movies
Page 2
mvOpen(3dm)mvOpen(3dm)
are orthogonal concepts. Single- or dual-fork movie files may contain
external references, and therefore are not flattened movies, and a movie
whose data is entirely self-contained (i.e. flattened) may have its data
and metadata in one or two files (i.e. single- or dual-forks,
respectively).
SEE ALSOmvIntro(3dm), mvCreate(3dm), mvClose(3dm), mvIsReadOnly(3dm),
mvGetErrno(3dm), mvCopyFramesAtTime(3dm), mvOptimize(3dm).
Page 3
