readme

mpeng Lib

                             The MPEG Library

                               Version 1.3.1
                              8 August, 1999

MPEG decoding engine (c) 1992 The Regents of the University of California
Front end (c) 1994-99 Gregory P. Ward ([e-mail])

The MPEG Library is a collection of C routines to decode MPEG-1 video
streams to a variety of colour schemes.  Most of the code in the library
comes directly from an old version of the Berkeley MPEG player,
"mpeg_play", an X11-specific implementation that worked fine but
suffered 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/

as well as from the MPEG Library home page at

   http://starship.python.net/~gward/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 (Unix)
===========================

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 (say) 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
ftp://ftp.bic.mni.mcgill.ca/pub/mpeg/).

If you want to skip building these standalone executables, just run
"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 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 version of the library with reduced
functionality; only do it if your sole purpose in building the library is
to link it statically into a larger program (such as the GIMP) that takes
care of colour conversion itself.


BUILDING THE LIBRARY (Windows)
==============================

Starting with version 1.3.1, the MPEG Library should build under Windows
as well as Unix, using either Borland C++ 5.4 or Microsoft Visual C++
6.0.  Thanks to George Yohng <[e-mail]> for providing the
Windows port.

Separate batch files are supplied for each compiler; if you're using
Borland C++, just run

   build_bc

which will create a single library file (mpegbc.lib) in the "lib"
subdirectory.  For Visual C++, run

   build_msvc

which will create three library files in the "lib" subdirectory.  The three
versions of the library are:

   mpegc.lib    - for single-threaded applications
   mpegcmt.lib  - for multi-threaded applications
   mpegcrt.lib  - for applications which use the dynamically loadable
                  run-time library (msvcrt.dll)


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.


PROBLEMS?
=========

Anyone who has problems under Unix with configuring or compiling the
MPEG Library, or linking it with other software, should contact me
([e-mail]).

If you have problems with compiling or linking with the library under
Windows, please contact George Yohng <[e-mail]>, since he
provided the Windows port and batch files.

Problems with using the library (coredumps, memory leaks, and other
bugs; or misunderstood documentation) should first be dealt with by
re-reading the documentation, and then by reading the source code.

If, after carefully reading the documentation, conducting rigorous
experiments to isolate the source of the problem, and inspecting the
relevant source code, you *still* can't figure out what's going on,
contact me at [e-mail].  I will ask if you have read the
documentation, conducted experiments, and checked the source code,
remind you that the library is unsupported free software, and gratefully
accept a patch to fix any problems you may have found.


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 (across Unix versions) program to test
the Library: extras/mpegtest.c.  It is similar in structure to easympeg,
but with all 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 decode 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

  * Magnus Heldestat for providing patches to speed up full-colour
    dithering

  * Andrew Kuchling for extensive testing of beta versions of 1.2 on a
    variety of Unix platforms

  * Adam Moss for writing the mpeg plug-in for the GIMP, causing yet
    more demand for the library

  * George Yohng for porting the library to Windows


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

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

Copyright (c) 1994-99 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
[e-mail].

$Id: README,v 1.9 1999/08/09 00:33:38 greg Rel $