mpeg2dec - a free MPEG-2 video stream decoder

Written by Aaron Holtzman <aholtzma@ess.engr.uvic.ca>

Contributions by:
	Bajusz Peter <hyp-x@inf.bme.hu> - motion comp fixes
	Real Ouellet <realo@sympatico.ca> - g200 fixes
	Brion Vibber <brion@gizmo.usc.edu> - x11 fixes
	Franck SICARD <Franck.Sicard@miniruth.solsoft.fr> - x11 fixes
	H}kan Hjort <d95hjort@dtek.chalmers.se> - Solaris fixes
	Didier Gautheron <dgautheron@magic.fr> - bug fixes
	(let me know if I've forgotten anyone)

First of all, this is very early code. If you're not interested
in hacking video codecs then there isn't much point in downloading
it. Normally I wouldn't release something this early, but it seems
like there is a lot of interested hackers out there so...

mpeg2dec is the result of me attempting to re-write the slice 
level and below code of the MPEG software simulation groups (MSSG)
decoder. After a few days of pain I decided I was better off 
re-writing the entire thing. I think my code is pretty easy to
read and understand. I'd love to have some feedback on the design.

Here's a hierarchy of how the code fits together:

decode.c
|--parse.c
|-----bitstream.c
|-----getvlc.c
|-----stats.c
|--mb_buffer.c
|--idct.c
|--motion_comp.c
|--display_*.c

For each frame, decode.c uses parse.c to stuff macroblocks into the
macroblock buffer (mb_buffer.c). When this buffer is full or the frame
is done, the main decoding pipeline (idct, motion_comp) 
is run over the contents of the buffer.

Modules with optimized code for a particular architecture have an
_foo suffix (like idct_mmx.c). The appropriate code is selected
at runtime in the case of instructions that aren't always available
supported (like 3dnow or SSE). The philosophy is "one binary->one
architecture".

Stuff that works
- I-type Frame pictures 

Stuff that is broken
- field based pictures
- P,B type pictures  (motion_comp.c needs some filling in)

Stuff that needs to be done
- fix the broken stuff (see above)
- the MSSG getvlc.c needs to be sanitized and turned into vlc.c
- motion.c need to be sanitized and pulled into parse.c 
  (in cvs 'bp_frames_branch')
- make it really fast :)

Patches

If you manage to fix bugs or add features to mpeg2dec, please send a 
patch to <aholtzma@ess.engr.uvic.ca>. Patches must be in 'diff -urN'
format. Also, if you send me assembly, it must be in AT&T format and
preferably inline assembly. Special ISA extensions (like 3dnow,MMX)
should be #ifdef'ed with the appropriate _ISA_, not the extension.
You should also include a test to determine if you extension is present
and set the appropriate function pointers.

How to use mga_vid from scratch

1. mknod /dev/mga_vid c 178 0
2. ./configure
3. if you have a g200 you might want to change the memory size in 
   mga_vid.c to 8 megs.
4. make
5. su 
6. /sbin/insmod videodev; /sbin/insmod drivers/mga_vid.o  (you must have 
   v4l built for your kernel)
7. ./mpeg2dec foo.mpeg2  (you're done!)

How do I know if mga_vid works on my system?
  
There is a test application called mga_vid_test. This test code should
print out info on the console about your specific card (G200 or G400,
as well as RAM size).  RAM size autodetect was only tested on a G200,
8MB so far... Also it should draw some nice 256x256 images for you,
if all is working well.


Documentation

If you need the mpeg-2 video spec, you can get it on www.wotsit.org
(mpeg2-2.doc). 

Aaron Holtzman,
December 1999

