                            The MPEG Library

                             Version 1.3.0
                           26 November, 1998

MPEG decoding engine (c) 1992 The Regents of the University of California
Front end (c) 1994-98 Gregory P. Ward (greg@bic.mni.mcgill.ca)

The MPEG Library is a collection of C routines to decode MPEG-1 movies
and dither them in a variety of colour schemes.  Most of the code in the
library comes directly from an old version of the Berkeley MPEG player,
an X11-specific implementation that works fine, but suffers from minimal
documentation and a lack of modularity.  A front end to the Berkeley
decoding engine was developed by Greg Ward at the Montreal Neurological
Institute in May/June 1994 to facilitate the development of an MPEG
player specifically for Silicon Graphics workstations; the decoding
engine together with the MNI front end constitute the MPEG Library.


AVAILABILITY
============

Both the above-mentioned SGI-specific MPEG player (glmpeg_play) and
the MPEG Library itself are available from

   ftp://ftp.bic.mni.mcgill.ca/pub/mpeg/

Several other MPEG-related goodies are gathered here as well, in
particular the MPEG encoder/decoder from the Portable Video Research
Group at Stanford University.  (They are not necessarily up-to-date
versions, though.)

Like any self-respecting open source project nowawdays, the MPEG Library
has its own WWW home page:

   http://www.bic.mni.mcgill.ca/~greg/mpeglib/

The original Berkeley decoder is available at

   ftp://mm-ftp.cs.berkeley.edu/pub/multimedia/mpeg/play/

A great many other MPEG goodies (another encoder, sample MPEG files,
etc.) can also be found on this FTP site -- good hunting ground for the
budding MPEG hacker.


BUILDING THE LIBRARY
====================

The MPEG Library comes with a GNU-style configure script, meaning that
building it should be a simple matter:

    ./configure
    make

Note that you must have an ANSI-compliant compiler to build the library.
In general, you should use the same compiler on all code that is to be
linked together; this means that (for example), compiling ImageMagick or
the GIMP with compiler X (ANSI compliant or not), and then linking with
an MPEG library built with compiler Y, is just asking for trouble.  

The configure script does make a good effort to find an ANSI-compliant
compiler.  The default is to use gcc, or cc if that's not found.  If gcc
is not found and cc is not ANSI-compliant, configure then takes a chance
and looks for acc -- the alternative ANSI compiler provided by Sun (at a
price).  (Of course, this is probably only meaningful on Sun platforms.)
If none of these are found, configure crashes -- you'll have to run it
again, telling it the name of the compiler to use (see below for how to
do this).

Customizing the configuration
-----------------------------

You can set a number of environment variables before running `configure'
to customize its operation.  All of them customize the pre-processing,
compilation, and linking stages:

   CC            C compiler to use
   OPTIMIZE      compiler optimization/debugging flags
   EXTRA_CFLAGS  any other compiler flags to use
   INCLUDE_DIRS  -I flags for the pre-processor
   DEFINES       -D or -U flags for the pre-processor
   EXTRA_LDFLAGS extra linker flags to use when building the 
                 standalone executables (mpegtest and easympeg)

For instance, on an SGI system, you might wish to use cc instead of gcc
(SGI's compiler generally compiles a lot faster than gcc, and generates
slightly faster code.)  You could then run `configure' as follows:

   CC=cc ./configure

(That's assuming a Bourne-style shell, such as sh, zsh, ksh, or bash.
For C-shell and descendents, use "env CC=cc ./configure".)

Or you might need to specify extra flags to put your compiler into ANSI
mode; this is necessary on some versions of HP-UX as follows:

   CC=cc EXTRA_CFLAGS=-Aa ./configure

Or if your compiler is broken and generates bad code with -O2 (the
default), you could tone down or turn off optimization:

   OPTIMIZE=-O0 ./configure


Customizing the build
---------------------

All of the variables above can also be overridden at build time, e.g.

   make CC=gcc EXTRA_CFLAGS=-Wall

to use gcc and make it emit lots of warnings.  It's generally better to
do the overriding at configure time, so that `configure' uses the same
flags for compiling test cases as you'll be using to compile the
library.


Build targets
-------------

The default behaviour when you run "make" (or "make all") is to build
the library plus whatever standalone executables are supported on your
system.  Source for the standlone executables lives in the `extras/'
subdirectory.  The simple test program `mpegtest' is always built; it
just decodes an MPEG stream, optionally computing a checksum of each
decoded frame.

On IRIX systems (SGI workstations), you will also get `easympeg', a
simple MPEG player that works under GL.  This is provided solely as an
example of how little code is needed to make a working MPEG player with
the MPEG Library; if you're interested in a full-blown MPEG player for
SGI workstations, take a look at my glmpeg_play (available from the same
location as the MPEG Library).

If you want to skip building these standalone executables, just say
"make lib".


Nit-picking optimizations
-------------------------

If you are building the library *exclusively* for use with a larger
program that takes care of all colour conversion tasks (such as
ImageMagick or the GIMP [?]), then you can save a bit of code size by
omitting most of the colour conversion code supplied with the library.
In this case, just run

   ./configure --disable-dither

and you will build a reduced version of the library.  This is not
necessary to compile or link successfully -- it'll just save a little
space.

Note that this will result in a crippled version of the library; only do
it if your sole purpose in building the library is to link it statically
into a larger program (such as ImageMagick or the GIMP) that takes care
of colour conversion itself.


Anyone who has problems configuring or compiling the MPEG Library, or
linking it with other software should contact me
(greg@bic.mni.mcgill.ca).


HOW TO USE THE LIBRARY
======================

There is a short but (hopefully) complete document in the "doc/"
subdirectory of the MPEG Library distribution.  This is supplied in
both PostScript form and as LaTeX 2e source.  Comments and suggestions
on the documentation are welcome.


EXAMPLES AND TESTING
====================

For a very simple MPEG player that uses the SGI Graphics Library to
display frames, take a look at easympeg.c, included in the "extras/"
subdirectory of this distribution.  (If you configured and built the
library on an SGI platform, easympeg should have been automatically
built for you.)  Even if you don't have an SGI, the source code can be
instructive -- the calls to GL functions are not too intrusive, and not
too hard to figure out either.  Also, it ought to be possible to convert
this program to OpenGL for improved portability.

There is also a simple, portable program to test the Library:
extras/mpegtest.c.  It is similar in structure to easympeg, with any
display-related code removed, and with the addition of code to time the
playback and to compute simple image checksums.  The timing code may be
of interest (eg. to answer questions such as "Can I achieve a playback
rate of X on platform Y?" or "How much faster will playback be if I
dither to shades of gray instead of full 24-bit colour?"), and the
checksum code provides a way to ensure that the library returns
identical results across platforms (which is currently *not* the case,
for reasons unknown to me).  Run "mpegtest <mpegfile>" to just get
timing information on the MPEG in <mpegfile>; add the "-checksum" option
to get checksum information; add "-dither <mode>" to try out various
dithering modes.  The possible values of <mode> are: "hybrid",
"hybrid2", "fs4", "fs2", "fs2fast", "2x2", "gray", "fullcolor", "none",
"ordered", "mono", "mono_threshold", "ordered2", and "mbordered".

A tiny MPEG stream, test.mpg, is included with the distribution.  You
can try mpegtest and easympeg on it, but don't expect perfection; for
one thing, the library does *not* give identical results across
platforms, so the results of running "easympeg -checksum" will not be
consistent.

I have also written glmpeg_play, a full-fledged MPEG player for SGI
platfoms (with frame-buffering, interactive controls, dynamic zooming,
etc.).  It is available via anonymous ftp as explained above.


FUTURE DIRECTIONS
=================

None planned, many required.  The MPEG Library is based on an
out-of-date version of the Berkeley X11 MPEG player ("mpeg_play"), and
should be updated to the latest version of mpeg_play.  The current
version is heavily dependent on global variables -- thus it's not even
remotely thread-safe, and you can't interleave the decoding of two
streams.  This is definitely not desirable, and could be fixed by
catching up with mpeg_play.  The MPEG Library should be restructured so
that it is easier to keep in sync with the Berkeley code in future.  All
external identifiers should be renamed to avoid conflict with other
code, and the interface revamped to be clearer, more consistent, and
modular for multi-threaded code and interleaved decoding of multiple
streams.  The library should probably be renamed to make it clear that
it only handles decoding of MPEG-1 video streams (there's a lot more to
the MPEG world now than there was in 1994).

However, none of this will happen unless others step in to fill the
breach.  I have little to no interest in multimedia or desktop video,
and do not intend to devote any significant time or energy to
maintaining the MPEG Library.  (This is entirely consistent -- it has,
after all, taken me nearly three years to get this minor bugfix release
out!)  So: if you *are* interested in seeing an open-source, documented
library for decoding MPEG video streams become a better, more
widely-available and used thing, then please get in touch with me.  I'd
love to hand this code over to someone willing and able to look after
it.

Late-breaking news: I just discovered the MPEG Software Simulation
Group's (MSSG) free MPEG-2 codec (that's "coder/decoder", if
you're not up on your MPEG jargon).  This looks like what the MPEG
Library should grow up to be if there was anyone to grow it.  I'll
continue to release bug fixes to the MPEG Library, but I strongly
suggest that anyone writing new MPEG code should at least look at the
MSSG's work:

   http://www.mpeg.org/MPEG/MSSG/


ACKNOWLEDGEMENTS
================

Thanks to John Cristy for making the MPEG Library an optional add-on
to ImageMagick, providing me with more free publicity (and lots of
traffic on our ftp site!) than I could have imagined, and for
suggesting some important fixes early on.  Also to Magnus Heldestat
for providing patches to speed up full-colour dithering; and to Andrew
Kuchling for extensive testing of beta versions of 1.2 on a variety of
Unix platforms.  And to Adam Moss for writing the mpeg plug-in for the
GIMP, causing yet more demand for the library -- and one more impetus to
get this bugfix release out!


COMPLETE LACK OF WARRANTY
=========================

This software is supplied without even the faintest shred of assurance
that it works in its entirety.  

Copyright (c) 1994-98 by Gregory P. Ward.
All rights reserved.

This file is part of the MNI front end of the Berkeley MPEG decoder.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose, without fee, and without written agreement is
hereby granted, provided that the above copyright notice and the following
two paragraphs appear in all copies of this software.

IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE
UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER
IS ON AN "AS IS" BASIS, AND THE AUTHOR HAS NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.  

Please drop me a line if you use the MPEG Library, either successfully
or not.  And if you use it unsuccessfully and find a nice, easy fix,
do please let me know about it!  My email address is
greg@bic.mni.mcgill.ca.

$Id: README,v 1.7 1998/11/26 19:09:04 greg Rel $
