mpeg_lib.tex

mpeng Lib

The colour map is accessed via the \code{Colormap} field of
\code{ImageDesc}, which points to an array of \code{ColormapSize}
colour map entries.  Each colour map entry is a structure of the form
\begin{verbatim}
typedef struct
{
   short red, green, blue;
} ColormapEntry;
\end{verbatim}
and the colour map is created when \code{OpenMPEG()} is called.  If no
colour map is created (i.e., the dithering mode is
\code{FULL\_COLOR\_DITHER}), then \code{ColormapSize} will be -1 and
\code{Colormap} will be \code{NULL}.  For example:
\begin{verbatim}
   char      *filename;
   FILE      *MPEG;
   ImageDesc MPEGInfo;

   filename = argv[1];

   /* Prepare to read and decode an MPEG stream */

   MPEG = fopen (filename, "rb");
   if (!OpenMPEG (MPEG, &MPEGInfo))
      exit;

   /* Do we have a colour-mapped mode? */

   if (MPEGInfo.Colormap != NULL)
   {
      for (i = 0; i < MPEGInfo.ColormapSize; i++)
      {
         mapcolor (i, MPEGInfo.Colormap[i].red,
                      MPEGInfo.Colormap[i].green,
                      MPEGInfo.Colormap[i].blue);
      }
   }
   /* ... */
\end{verbatim}
Here, we assume that the function \code{mapcolor()} is available to
set the system colour map.

% NOTE to self: check how mpeg_play generates colour maps again;
% after all, its pixel values are 8 bits too, so it can't be using
% a huge colour map to keep from clobbering X's.  Problem basically
% is that grayscale dithering uses a 256-elt. colour map, which clobberss
% the system map on the 4D35's -- on Indy's too?  portia?

%Actually, the situation is slightly more complicated: if it were literally
%like this, then programs that use the MPEG Library would be stuck with
%using entries 0-255 (or 0-127, depending on the dithering mode) of the
%system colour map.  On windowed systems such as X Windows, this is often
%undesirable, as it might clobber colour map entries used by the system or
%other programs.  Thus, the MPEG Library provides a mechanism for mapping
%``ideal'' colour map indeces (which are in the range 0..127 or 255) to 
%real-world colour map indeces.  This 

\subsection{Image data format}
\label{sec:image_data}

The image data, as returned by \code{GetMPEGFrame()}, is formatted in
a straightforward way.  Pixels are stored in row-major order, starting
at the upper left-hand corner of the image.  The number of bits
allocated per pixel is given by the \code{PixelSize} field of
\code{ImageDesc}.  This is illustrated in
Figure~\ref{fig:image_format}, which shows a sample $8 \times
10$-pixel image, with the offset into the image data for each pixel.
If the pixels are 8 bits each, then this will be a simple byte offset.

\begin{figure}[htbp]
  \centerline{\psfig{figure=image_format.eps}}
  \caption{Illustration of image data layout for a sample $8 \times 10$
    image.  The number at each pixel is just the offset into the image
    data array.}
  \label{fig:image_format}
\end{figure}


\section{Programming Reference}

\subsection{The \code{ImageDesc} structure}
Relevant declarations:
\begin{verbatim}
typedef struct
{
   unsigned char red, green, blue;
} ColormapEntry;

typedef struct
{
   int  Height;             /* in pixels */
   int  Width;              
   int  Depth;              /* image depth (bits) */
   int  PixelSize;          /* bits actually stored per pixel */
   int  Size;               /* bytes for whole image */
   int  BitmapPad;          /* "quantum" of a scanline -- */
                            /* each scanline starts on an even */
                            /* interval of this many bits */
   int  ColormapSize;     
   ColormapEntry *Colormap; /* an array of ColormapSize entries */
} ImageDesc;
\end{verbatim}

This structure provides (hopefully) all the information needed to
display an MPEG stream, although it doesn't necessarily provide all
the information you could possibly want to know about such a stream.
However, that's not the intent of the MPEG Library; if you really need
to know, for instance, just how many intra-frames are in a particular
MPEG, you might want to take a look at the \code{mpegstat} program,
which was also based on the Berkeley X11 player.%
\footnote{\code{mpegstat} should also be available at
   \code{ftp://ftp.bic.mni.mcgill.ca/pub/mpeg}.}

Here is the list of fields in the structure:
\begin{ttdescription}{ColormapSize}
\item[Height] the height, in pixels, of the movie.
\item[Width] the width, in pixels, of the movie.  Note that due to the
  block nature of MPEG encoding, the height and width will always be
  multiples of 16.
\item[Depth] the number of bits per pixel that are actually relevant
  to the display.  For most dithering methods, this will be 8 (i.e.,
  we usually use an 8-bit colour map); for full-colour dithering, it
  will be 24.
\item[PixelSize] the number of bits (not bytes!) of storage allocated
  per pixel.
\item[Size] the size, in bytes, of one entire unencoded frame.  This
  is simply equal to \code{Height*Width*PixelSize/8}.  (Note:
  currently, \code{BitmapPad} is ignored in the calculation of
  \code{Size}.)
\item[BitmapPad] the ``quantum'' of a scan line; i.e., each scan line
  starts on an even interval of this many bits.
\item[ColormapSize] the number of entries in the colour map.  This is
  usually 128, but for most dithering methods it can be indirectly
  modified by the user of the Library.  It is zero in non-colourmapped
  modes.
\item[Colormap] the table used to map pixel values to
  red/\-green/\-blue values (which are themselves stored as bytes in
  the \code{ColormapEntry} structure.  It is \code{NULL} in
  non-colourmapped modes.
\end{ttdescription}


\subsection{\code{SetMPEGOption()}}
\prototype{void SetMPEGOption (MPEGOptionEnum Option, int Value)}
\noindent\code{Option} should be one of:
  \begin{ttdescription}{MPEG\_CMAP\_INDEX}
  \item[MPEG\_DITHER] Sets the dithering mode, which controls how YCrCb
    values are converted to RGB space.  \code{Value} should be a
    \code{DitherEnum} value, cast to \code{int}.  Dithering modes are
    explained above, in section~\ref{sec:dithering}.

  \item[MPEG\_LUM\_RANGE]
  \item[MPEG\_CR\_RANGE]
  \item[MPEG\_CB\_RANGE] These set the ranges of luminance and
    chromaticity values.  The defaults are 8, 4, and 4.  (I do
    not understand the effects of changing these; my experiments
    indicate that doing so garbles perfectly good colour maps.)

%  \item[MPEG\_CMAP\_INDEX] This allows you to set the mapping of
%    ``ideal'' pixel values (i.e., indeces into the colour map returned
%    by \code{OpenMPEG()} in the \code{Color\-map} field of the
%    \code{ImageDesc} structure) to ``real-world'' pixel values, or
%    indeces into the system colour map that you were able to allocate.
%    See section~\ref{sec:colour_maps} for more information on
%    colour-mapped modes.  The \code{Value} passed to
%    \code{SetMPEGOption()} should be a pointer to an array of
%    \code{unsigned char} with \code{ColormapSize} entries (cast to
%    \code{int}, of course).  The contents of this array will be copied
%    into a private Library array, so you don't need to worry about 
%    keeping it around after calling \code{SetMPEGOption()}.

  \end{ttdescription}

\begin{Notes}
  \code{SetMPEGOption()} allows you to set a variety of options related
  to MPEG decoding.  The possible values for \code{Option} are described
  above; the possible values for \code{Value} value are dependent on
  what \code{Option} you are setting.  Whatever \code{Value} is, it
  should of course be cast to an \code{int}.
\end{Notes}


\subsection{\code{OpenMPEG()}}
\prototype{Boolean OpenMPEG (FILE *MPEGfile, ImageDesc *Image)}
\begin{Arguments}{MPEGfile}
\item[MPEGfile] A file that is already open for reading, positioned at
  the beginning of an MPEG stream.
\item[Image] Pointer to a user-declared \code{ImageDesc} structure.
  You shouldn't change any of the fields in \code{*Image} yourself,
  either before or after calling \code{OpenMPEG()}; use
  \code{SetMPEGOption()} instead.
\end{Arguments}
\begin{Notes}
  \code{OpenMPEG()} prepares an MPEG stream for decoding.  It
  initializes internal data structures for decoding and dithering
  and---if applicable---creates a colour map.  After calling
  \code{OpenMPEG()}, the following fields in \code{*Image} will be
  set: \code{Height}, \code{Width}, \code{Depth}, \code{PixelSize},
  \code{Size}, \code{BitmapPad}, \code{ColormapSize}, and
  \code{Colormap}.
\end{Notes}


\subsection{\code{GetMPEGFrame()}}
\prototype{Boolean GetMPEGFrame (char *Frame)}
\begin{Arguments}{Frame}
\item[Frame] Pointer to a user-allocated chunk of memory.  Must have
  enough room for the decoded image, which can be determined from the
  \code{Size} field of \code{ImageDesc}.
\end{Arguments}
\begin{Notes}
  Decodes the next frame from the movie.  Returns \code{TRUE} if there
  are any frames left to decode in the movie, or \code{FALSE} if the
  decoded frame is the last frame in the movie.  That is, for a movie
  with $N$ frames \code{GetMPEGFrame()} will return \code{TRUE} $N-1$
  times, and then the call to decode the last frame will return
  \code{FALSE}.  After that, the behaviour of \code{GetMPEGFrame()} is
  undefined (unless you call \code{RewindMPEG()}.)
\end{Notes}


\subsection{\code{RewindMPEG()}}
\prototype{void RewindMPEG (FILE *MPEGfile, ImageDesc *Image)}
\begin{Arguments}{MPEGfile}
\item[MPEGfile] The open, readable stream pointer that was also passed
  to \code{OpenMPEG()}.
\item[Image] The image descriptor that was passed to and filled in by
  \code{OpenMPEG()}.
\end{Arguments}
\begin{Notes}
  Repositions \code{MPEGfile}'s file-offset pointer to point to the
  beginning of the stream, and reinitializes internal MPEG Library
  structures to prepare reading the MPEG again.  The first call to
  \code{GetMPEGFrame()} after calling \code{RewindMPEG()} will return
  the first frame of the movie, as though \code{OpenMPEG()} had just
  been called.
\end{Notes}

\section*{Acknowledgements}
Most of the credit for this package should go to the authors of
\code{mpeg\_play}; all I can really take credit for is shuffling code
around and coming up with a reasonably intelligent interface to the
decoding engine that does the real work.  

Thanks to Magnus Heldestat for contributing a sped-up version of
24bit.c, resulting in faster decoding/dithering of full-colour images.

\begin{thebibliography}{0}
  \bibitem{LeGall91} Didier LeGall, ``MPEG--A Video Compression
  Standard for Multimedia Applications,'' {\em Communications of the
    ACM\/}, April 1991, Vol 34 Num 4, pp. 46--58.

  \bibitem{Patel93} Ketan Patel, Brian C. Smith, and Lawrence A. Rowe,
  ``Performace of a Software MPEG Video Decoder'', {\em ACM Multimedia
    '93 Conference}.
\end{thebibliography}

\end{document}