------------------------------------------------------------------
MPEG2AVI.EXE v0.16B33 10/31/99 FAQ, NOTES
VideoForWindows and YUV pixel-formats
------------------------------------------------------------------

(v0.15B5 adds YUY2 AVI-mode '-o9')
(v0.15B51 *hopefully* fixes all prior MPEG2AVI issues with codec-setup)

(0.15B51 codec compatibility table updated,
         Document error corrected, "PicVideo 4/1/1 = 4:2:0" )
(0.16B23 added a few FAQ)

===
FAQ
===

What is "YUV"?
--------------
The letters "YUV" refer to a color-space.  Most users are familiar
with the RGB color-space : a color-value is defined by three
the additive components red, green, and blue.  YUV defines in
terms of "brightness" (Y) and color-difference (U.V)

For a more detailed explanation, see http://www.webartz.com/fourcc 

What is YV12?
-------------
"YV12" is a Directdraw surface type.  MPEG-Video's YUV420 profile
and "YV12" share identical image resolution : 
	The Y-plane is stored at full resolution (eg 720x480.)  
	The U-plane and V-plane are stored ath alf-resolution (eg 360x240.)
	Individual Y, U, V samples are 8bits per component.

What is YUY2?
-------------
YUY2 is a Directdraw surface type.  MPEG2 Video's YUV422 profile
and "YUY2" share identical image resolution :
	The Y-plane is stored at full resultion (eg 720x480.)  
	The U & V-planes are subsampled horizontally (eg 360x480.),
       but not vertically.
      There is one Y-sample for each image pixel, but only 1 pair of 
      U/V samples for every two pixels.

What makes the YUV format a better choice for VFW compression?
---------------------------------------------------------------
First, most AVI codecs perform compression in the YUV color space.
When the input video is supplied as YUV, the codec does not waste time 
converting RGB data into YUV data.  Second, MPEG-video frames are 
processed in the YCbCr colorspace (YCbCr is a specific YUV format.
I use YUV and YCbCr interchangably in this document, but be aware that
there are many distinct YUV color-spaces.)  Thus between MPEG2AVI and the 
VFW codec, two color transformation cycles are eliminated :
  ( YUV -> RGB24, and RGB24 -> YUV )

MPEG-1 video always uses "YCbCr420", whereas MPEG-2 bitstreams can 
optionally use 422 or 444 (in place of 420).  These "denser" formats are often used in editing/production systems where every effort is made to 
preserve detail.)  Consumer applications (including DVD and DTV) generally use 420.

For a given image size, a 420 frame requires less storage RAM (because the
chroma-components are half-resolution) than an RGB24 frame.  Less data 
means faster manipulation & transport (usually.)

What are possible disadvantages to using a YUV format with VFW compression?
---------------------------------------------------------------------------
Unfortunately, MPEG-2 Video supports several different color-spaces. 
Although they all use the same component video sampling (420/422/444),
the samples are quantized using different formulas.  Thus, writing an 
AVI file directly in YUV-format loses the original palette.  In the
worse case, the color-difference leads to a color-mismatch or shift when 
the AVI is later played. 

(I was originally under the impression that YUV-AVI guarantees better
 color accuracy, but I am wrong.) 

Furthermore, MPEG2AVI's YUV-AVI modes (-o8 and -o9) use an alternate
method to write AVI-files.  So far no problems have been encountered, but
there is a possibility a codec you try, will not work with YUV-AVI.

Which is better, MPEG2AVI's YUY2 or MPEG2AVI's YV12 mode?
---------------------------------------------------------
There is no simple answer to this question.

Nearly all codecs convert video to YUV-format, then process it.  With 
these codecs, any YUV-format is preferable to RGB24.  But choosing the
best YUV format, requires specific knowledge about the *source MPEG* and
the *destination AVI.* :

  1)  What "color profile" is the source video (after any MPEG2AVI 
      manipulations) ?
 
      Although most MPEG-files are 420, some MPEG2AVI filters (like half-
      resolution '-2') will end up "promoting" the effective profile to 444.
      This means, the processed-video possesses full color detail (444)

  2)  Does the AVI codec chroma-subsample the video?

      Some M-JPEG codecs support several subsamplers (422, 444, 411.)
      The subsampler choice may be implicint (i.e. tied to the input
      format.)  PicVideo's M-JPEG codec lets the user control the
      subsampling.

      Assuming that the encoding-job requires preservation of maximum
      detail possible, then the choice of YUV-AVI format is dictated
      by the AVI codec's color subsampling.  Most codecs subsample at
      4:2:0 or even less (less color resolution)

      If you cannot choose the subsampling, or don't know, assume that
      it is 420 (or worse.)  Only a few AVI codecs preserve more color
      detail.

      There are a few codecs (Indeo 5.x) which actually prefer RGB24 
      input.  These are the exceptions, not the rule.

And some codecs, like PicVideo's M-JPEG codec, don't support YV12-mode, 
so the choice is between RGB24 and YUY2.  RGB24 has higher color-
resolution than YUY2 (potentially offering better image-quality), 
but YUY2 is faster.  Because the PicVideo codec lets the user pick a
subsampling factor, use 111 for RGB24 and 422 for YUY2.

Which VFW codecs work with MPEG2AVI's YUV-modes (YV12, YUY2)?
-------------------------------------------------------------
Before continuing, it is important to understand that MPEG2AVI's
YUV-AVI mode(s) aren't perfect.  The AVIwriter uses a non-standard 
Method to write YUV AVIstreams, and we all know departure from standard documented methods risks compatibility problems with Microsoft products.

Only one codec has been tested 100% successfully : Morgan Multimedia's M-JPEG works with all of MPEG2AVI's output methods (RGB24, YV12, YUY2.)

Unfortunately, the resultant AVI files have different length, leading me to believe that Morgan's M-JPEG codec selects a subsampling factor based on input-format. 

As for Microsoft's MPEG-4 codec, 0.15B51 finally sets up the compression
job correctly (using ICSeq....() calls.)  Unfortunately, the release version of Windows Media Tools 4.0 no longer supports VideoForWindows.  This means the precious MPEG-4 codecs are the exclusive technology of Windows Media (*.ASF)

You can use MPEG2AVI with the older 04/99 beta MPEG4 codec, but remember its just a beta-version.  The beta-version has trouble dealing with high-motion content at low-bitrates. (This is not an MPEG2AVI problem.) 

The codec-support table below shows all the codecs I've tried with MPEG2AVI's YUV-modes.  As it turns out, few VFW codecs support YUV input.

===================

Codec support table
===================
                         Codec Compatibility chart
     --------------------------------------------------------------------
              command  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17
     AVImode    line
     AVI RGB24  '-o7'  X  X  X  X  X  X  X  X  X  X  X  X
     AVI YV12   '-o8'  X  X  X  X     X
     AVI YUY2   '-o9'  X  X  X  X  X  X        ?

          ? means DVMPEG accepts this format, but crashes

     1 = Microsoft MPEG-4 v1 (04/09/99 beta Build 3688)*
     2 = Microsoft MPEG-4 v2 (04/09/99 beta Build 3688)*
     3 = Microsoft MPEG-4 v3 (04/09/99 beta Build 3688)*
     4 = Morgan Multimedia M-JPEG v1.0**
     5 = PicVideo M-JPEG v2.0***
     6 = VDOnet VDOWave
     7 = Paradigm Matrix M-JPEG v1.13
     8 = Intel Indeo 3.x/4.x/5.x
     9 = Darim DVMPEG 5.00

     *The release versions (08/09/99) of Microsoft MPEG-4 do *NOT* work
      with VFW!  Microsoft dropped VFW support to promote Windows Media (ASF)!
      Microsoft MPEG-4 always subsamples to 4:2:0, so YUY2 offers no quality
      advantage over YV12, so you should use YV12 since it is faster.
      (but with MPEG-2 "CHROMA422" bitstreams, YUY2 mode is faster!)

     **There seems to be a bug with YUV input modes and "Invert field order"
       Problem seems to happen only with video-sizes > 288 lines.  
       I believe Morgan's codec autoselects a subsampling mode based on the 
       input format (YV12 selects 4:2:0, YUY2 selects 4:2:2)  Use YUY2 for 
       higher quality, use YV12 for faster compression.

     ***Don't bother using subsampling mode "4/4/4" for YUY2, overkill.
        When using RGB24, use "1/1/1" if operating in half-resolution (-2)
        otherwise pick 4/2/0. Neither the Wavelet2000 nor lossless-JPEG codecs
        support YUV.

     The version of Paradigm Matrix M-JPEG that I tested, v1.13,
     does not support YUV input :(

(MPEG2AVI's ICCompressor() dialog-box will also show "No Recompression"
and "Full frames."  Neither of these work, unfortunately.  Windows VFW 
does not support raw YUV frames, although a third-party could provide
such support.)

========================================
Recommended AVI-mode for best quality
========================================

     Codec : PicVideo M-JPEG
    ========================================
                             Output-mode
        Input             Full          Half ('-2')
        bitstream         resolution    resolution
        
        MPEG-1            YV12*         RGB24, YUY2
        MPEG-2 CHROMA420  YV12*         RGB24, YUY2

        MPEG-2 CHROMA422  YUY2          RGB24, YUY2

        MPEG-2 CHROMA444  RGB24         RGB24, YUY2

        *Current PicVideo M-JPEG does not support YV12 (use YUY2 instead)
         (configure the codec for 4/1/1 subsampling)

        The RGB24 format has effective subsampling of "1/1/1", but
         requires YUV->RGB conversion cycle through MPEG2AVI.

        Notes : Configure "subsampling 1/1/1" for RGB24
                Configure "subsampling 4/2/2" for YUY2
                Configure "subsampling 4/1/1" for YV12

    Codec : Microsoft MPEG-4 (04/09/99 beta release)
    ========================================

       Use YV12 for all modes.  I believe the MPEG-4 codec internally subsamples
       the input-bitmap to 4:2:0.


    Codec : Morgan Multimedia M-JPEG v1.10
    ========================================
                             Output-mode
        Input             Full          Half ('-2')
        bitstream         resolution    resolution
        
        MPEG-1            YV12          YUY2
        MPEG-2 CHROMA420  YV12          YUY2

        MPEG-2 CHROMA422  YUY2          YUY2

        MPEG-2 CHROMA444  YUY2          YUY2

        The RGB24 format has effective subsampling of "1/1/1", but
        Morgan's documentation do not list 1/1/1 as a supported
         mode.

'RGB24'= '-o7'  (24 bpp RGB packed-pixel)
'YV12' = '-o8'  (16 bpp YUV packed-pixel)
'YUY2' = '-o9'  (12 bpp YUV planar-pixel)

(Don't worry about the bpp values.  All samples are 8bits/component, so
 YV12 has the same color-gamut (24bit palette) as RGB24.  The lower bpp
 values indicate some sharing of color-samples among a group of pixels.)

===============
Troubleshooting 
===============

Q:  When I use YUV mode ('-o8' or '-o9'), the Codec-selector box doesn't show
    any codecs, only "No Recompression" and/or "Full Frames"!

    That means no codec on your system supports your the input-parameters
    selected for MPEG2AVI.  Double-check that the output dimensions
    are divisible /16.  ("No recompression" won't work because VFW only
    supports raw RGB video.)

    ---
     
Q:  When I try to compress using Microsoft MPEG-4 codec, I get the
    error message "AVIStreamSetFormat() : Couldn't set format!"

    Windows Media Tools 4.0 FINAL (08/09/99) does not support MPEG-4 
    compression through VFW.  According to Microsoft, the Windows Media 
    Audio/Video codecs (which MPEG-4 is a part of) are authorized *only* for
    Windows Media files (ASF).  You may be able to find an older
    beta version of the MPEG-4 codec (MPG4C32.DLL 04/09/99) on older
    mirror sites.

    Note that Microsoft has pledged MPEG-4 v1, v2 compatibility in
    *future* Windows Media Player releases.  The MPEG-4 v3 codec is
    now exclusive to Windows Media Technologies (ASF)

    ---

Q:  Where can I get the older/beta Microsoft MPEG-4 codec?

    Use the search engine http://ftpsearch.ntnu.no (or ftpsearch.lycos.com)

    Search for the file "wmtools.exe", make sure the filesize is "4.2M"
    (The beta-distribution is 0.1M larger than the 08/99 release version.)

    This is 100% legal, as Microsoft publically distributed its wmtools
    package, even during beta-testing.  The beta-version has no expiration
    date.
    
    ---

Q:  When I compress using Microsoft MPEG-4 codec and YV12/YUY2 mode,
    the keyframe placement is erratic.  

    Microsoft's MPEG-4 determines optimal placement of keyframes.  The
    "Keyframe Every [x] seconds" option merely places an *lower* limit
    on the *MINIMUM* keyframe frequency.  The codec can and will declare
    keyframes more often than the user-specified minimum, for better
    random-seek performance.  I assure you the RGB24-mode exhibits the 
    same behavior, except that key-frame information is not available

    ---

Q:  When I use MPEG2AVI's YV12 mode with Morgan-Multimedia M-JPEG codec,
    the output AVIs look "interlaced".  Why?

    v1.0 - Make sure that "Support interleave" is enabled for BOTH encode 
    and decode (read the manual!)  Under decompression, "Invert Fields" 
    should be enabled.  This is not an MPEG2AVI issue, because Microsoft's 
    MPEG4v3 codec does not exhibit this problem.  

    I haven't looked at this problem recently (Morgan has been through
    several updates since I wrote this response.)

    ---

Q:  When I compress the same MPEG video, I noticed the AVI filesize depends
    on the output-mode (RGB24/YUV, even with the exact same codec settings.
    Why?

    MPEG2AVI 0.15B4 was released prematurely.  It's YV12 AVI-writer did not
    properly reset the codec prior to use.  Note this problem occurs
    when the Microsoft MPEG-4 codec was used with MPEG2AVI's YV12-mode (-o8)

    Starting with 0.15B41, the codec-reset problem was fixed, but the 
    Microsoft MPEG-4 codec still did not use the correct KeyFrame rate.
    However, the codec bitrate was correct.

    Starting with 0.15B5, YUV-AVI mode posts the ICM_COMPRESS_FRAMES_INFO 
    message, to the codec.  This *finally* squashes the KeyFrame-rate issue
    with Microsoft's MPEG-4.  Unfortunately, the codec bitrate-control is
    now inaccurate.  You will have to play with the bitrate-control when
    using YUV-AVI mode and Microsoft MPEG-4.

    MPEG2AVI 0.15B51 fixes the bitrate-inaccuracy introduced by 0.15B5.
    I hope *all* the previous issues with YUV-AVI have been fixed.
    YUV-AVI should now oerate just like RGB-AVI.
    associated with YUV-AVI modes.  In YUV mode, MPEG2AVI now sets up the
    codec with this code sequence.  

      ICCompressorChoose();
      ICGetState( hic, lpCodecSettings, cbState ); // remember user's settings
      ICSetState( hic, NULL, cbState );  // reset codec
      ICSetState( hic, lpCodecSettings, cbState ); // restore user's settings
      ICSeqCompressFrameStart();

      Apparently, only the PicVideo and Microsoft MPEG-4 codec require
      such extensive setup.  Morgan M-JPEG uses the dialog slider-bar 
      'data-rate', which escapes the foobar.

    (In RGB mode, only ICCompressorChoose is called.  MPEG2AVI then calls
     AVIStreamMakeCompressed(), which manages the rest.)
    ---

Q:  Why isn't there any keyframe information when I use RGB24 AVI mode '-o7'?

    In '-o7' mode, MPEG2AVI uses a writing-function copied out of Microsoft's 
    platform-SDK (WRITEAVI.C)  The library functions in question don't return 
    keyframe information. 

    In YUV AVI mode ('-o8' or '-o9'), MPEG2AVI manually compreses a
    video-frame by calling ICSeqCompressFrame().  Upon returning,
    ICSeqCompressFrame() marks the current frame is a keyframe or non-kf.
    (The compressed-data is written with AVIStreamWrite() )

    ---

Q:  Since MPEG2AVI doesn't support audio, how could I extract the
    audio of a VOB file?

    Earlier I hinted at future integrated AC-3 audio decoding.  Unfortunately, 
    I have to back away from this claim.  There are licensing issues involved
    with AC-3 decoding.  Simply put, MPEG2AVI cannot decode AC-3 audio
    legally, not without a full decoder license.  (In contrast, MPEG-video 
    decoding is free as long as the product remains free.)

    Anyway there are commercial tools which can manipulate AC3 bitstreams.
    If you can't afford one, you can always use the DirectShow SDK samples to
    pipe a softDVD audio decoder to a WAV file.  (Of course, a Directshow
    DVD-player must be installed.)  Keep in mind that audio content and video
    content are protected by copyright laws.

    ---

Q:  Encoding AVI files with MPEG2AVI is slow. How can I encode AVIs faster?

    MPEG2AVI is mostly C-code written by standards committee.
    The decoder was coded for academic readability, not performance. 
    MPEG2AVI does have some MMX optimizations, but many features (like -3x, 
    -3y) are not yet optimized.

    There are three things you can try to improve MPEG2Avi performance:

    1) If possible, use the YUV-AVI modes (-o8 or -o9.)  Either YUV-mode is
       faster than the RGB24-AVI mode (-o7.)  But some video compressors do
       not support YUV-input formats.

    2) Use the MMX IDCT Chen function ('-r2'.)  Decoding is slighty less
       accurate, but also slightly faster.

    3) If you have two hard drives, read from one and write to the other.

    4) Don't multitask during an encoding job.  I know Win9x is a multi-
       tasking operating-system, but due to the way Win32-console applications
       need to read the keyboard, they don't run well in the background. 

    As a last note, if each frame takes 1/2 second or more to encode,
    the bottleneck is the AVI codec, not MPEG2AVI!

    ---

Q:  When I preview an MPEG-file using '-o6' (GDI), the preview window
    is "locked", and always seems to go behind overlapping windows.

    I'm not a very proficient Windows-programmer, so I don't know how
    to code a fully functional application window using the plain old WinAPI.

    If you're a Windows programmer, and want to fix this, all the GDI code is
    In windisp.c (don't laugh at my code, please)

    ---

Q:  Why is the resize-engine (-3X, -3Y) locked to 8-pixel increments?
    
    Because integer division is so slow on every CPU, the resize-engine uses 
    multiply and bitshift ops to approximate integer division.  The
    approximation places constraints on the input/output resolution values, 
    otherwise the 32-bit accumulator would saturate when scaling extremely
    large resolutions.  The reduced granularity is a tradeoff between
    speed and accuracy.

    Starting with v0.15B51, the resizer's granularity is always 8-pixels,
    regardless of the MPEG-video's CHROMA format.  (In v0.15B4, the
    CHROMA format could impose additional restrictions on the
    minimum allowable resize-increment.)

    Starting with v0.16B32, the Vresizers are partially MMX-optimized,
    though still relatively slow.  The only way to speed them further is
    to switch to a different algorithm (bilinear.)

    Bilinear filtering is good for zooming (enlarging) bitmaps, but
    less suitable for shrinking bitmaps.

    ---

Q:  Why is the '-# <start> <end>' option so slow?  Why does MPEG2AVI still 
    decode MPEG-video up until the starting frame?

    MPEG2AVI currently decodes every picture-header in the MPEG bitsream.
    Due to the manner in which MPEG-compression works, B-frames can be skipped
    (because they do not propogate picture information forward or backward.) 
    However, I/P frames serve as "reference frames", so they must always be
    Decoded, because the start-point may depend on a previous I/P frame.

    And no, a frame-counter is not a standard-feature of MPEG-bitstreams.  So
    I can't rely on the GOP-header info to seek to a specific frame.  Anyway,
    Many MPEG-editing tools let users cut and paste MPEG-sequences, which can
    Have the nasty side-effect of mangling the MPEG-timecode (another reason
    for MPEG2AVI to decode every picture-header and maintain an internal
    counter.)

    With VOB-files, you can use the LBA-seek command ('-@ <lba>'), because
    VOB-packets are fixed length.  Unfortunately, opening an MPEG-sequence in
    midstream can produce visual artifacts (because B-frames in a group-of-
    pictures can reference a previous key-frame.)  So through trial and error,
    you'd have to combine 2 commands : 1) LBA-seek ('-@') and
    2) frame-range ('-#').

    ---

-----------------------
MISCELLANEOUS QUESTIONS
-----------------------

Q:  Can I use MPEG2AVI to convert an MPEG-2 to MPEG-1 bitstream?

    Not directly.  MPEG-encoders are far more complicated than decoders.
    Besides, plenty commercial programs can convert AVI -> MPEG-1.

    Darim's offers an interesting software approach to generating MPEG-1
    files.  Their MPEG-encoder (DVMPEG) comes with a "front-end" for
    VideoForWindows.  DVMPEG's front-end allows any standard VFW 
    application write MPEG-1 bitstreams.

    It's a great idea, but I was dissatisfied with the resultant MPEG-1 
    quality.  Since I can easily check MPEG2AVI's output by writing an 
    uncompressed RGB24 AVI, a quick comparison among various software
    MPEG encoders revealed DVMPEG to be inferior. 

    I am considering a new output-mode for Adobe Premiere plug-ins.  This
    would let MPEG2AVI access the XingEncoder And Panasonic plug-ins, but
    this feature is somewhere in the distant future. (I did spend all of 5 
    minutes to convert MPEG2AVI's yuv/rgb24 convertor into yuv/rgb32 
    convertor, in anticipation...)

Q:  Do MPEG2AVI's MMX optimizations compromise decoding precision?

    Internally, NO.  As long as you stick with the IEEE-1180 IDCT
    functions (either '-r0' or '-r1'), MPEG2AVI(MMX)'s output should be
    "pixel-for-pixel identical" to the older, non-MMX MPEG2AVI.

    Unlike SoftDVD players, which are optimized for *real-time* playback,
    MPEG2AVI makes no computational shortcuts.  THough I doubt a casual
    comparison would show any difference between a softDVD player and
    MPEG2AVI.  XingDVD 2.0x sticks out like a sore thumb, due to its
    flawed motion-compensation routines.

    Off-hand I recall that my motion-compensation routines use a
    different pixel-rounding policy.  In the ISO code, the half-pel
    motion-compensation cases round source pixels before combining the
    dest pixels.  In MPEG2AVI, the source and dest and added together
    with full precision, then the total sum is rounded.  Numerically
    MPEG2AVI implements more accurate rounding, but it's not the method
    shown in MSSG's reference codec.  *Shrug*

    Externally (i.e. manipulation after the video has been decoded),
    the MMX YUV->RGB converter uses smaller (16-bit signed) coefficients. 
    So I suppose the MMX-CSC might introduce a +/- 1-quantization level
    difference for RGB24 modes.  But internal calculations are 32-bit, so 
    the impact should be minimal. 

    Now obviously, if you use the high-speed MMX IDCT functions, then
    YES, MPEG2AVI's decoding precision decreases.  Since performance
    doesn't increase a whole lot, I really recommend the  default
    ('-r1') 32-bit MMX IDCT.

Q:  What about 3D-Now optimizations, or P3 SSE optimizations?

    Except for the 3D-Now "pavgusb" instruction, there are no places
    where 3D-Now can beat MMX.  MPEG-decoding is largely an image-processing
    application, with few places for 32-bit floats.  And,
    I don't have an AMD 3D-Now CPU to play with.  Furthermore, the
    motion-compensation isn't causing a bottleneck in MPEG2AVI.

    I haven't looked at Intel's SSE, so I can't really comment.  Obviously,
    I'd need an SSE-CPU to play with.  Intel's developer-web page has some
    technical docs for an IEEE-1180 compliant IDCT function (using SSE), so
    at the very least a (slightly) faster MMX32 IDCT function could be
    implemented.

Q:  I don't like the command-line user-interface, are there plans to
    improve it?

    What?  </SARCASM ON> You mean you don't enjoy typing 6 command groups,
    separated by hyphenated numbers and letters?!?  Hmm... I have already
    failed...  </SARCASM OFF>

    yes I of all people know MPEG2AVI could stand to benefit from a better
    user-interface.  Most likely I'll first try to implement a "text
    script" interface (i.e. commands entered in a text-file format.)  That
    way users don't have to remember complicated command-line jobs.

=====
Links
=====

http://members.xoom.com/mpeg2avi - MPEG2AVI official homepage 
http://www.inmatrix.com
http://www.concentric.net/~psilon - VirtualDub

http://www.morgan-multimedia.com - Morgan Multimedia M-JPEG codec 
http://www.jpg.com - PicVideo M-JPEG codec
http://www.mjpeg.com - Paradigm Matrix M-JPEG codec 
http://developer.intel.com - Indeo Video Interactive 5 codec 
http://www.mainactor.de - MPEG encoder, M-JPEG codec 
http://www.darvision.com - Darim DVMPEG encoder, with VFW front-end
