ConvertToRGB / ConvertToRGB24 / ConvertToRGB32
ConvertToYUY2 / ConvertBackToYUY2 / ConvertToYV12

ConvertToRGB (clip [, string "matrix"] [, bool "interlaced"])
ConvertToRGB24 (clip [, string "matrix"] [, bool "interlaced"])
ConvertToRGB32 (clip [, string "matrix"] [, bool "interlaced"])
ConvertToYUY2 (clip [, string "matrix"] [, bool "interlaced"])
ConvertToYV12 (clip [, string "matrix"] [, bool "interlaced"])
ConvertBackToYUY2 (clip [, string "matrix"])

matrix: Default Rec601. Controls the colour coefficients and scaling factors used in RGB - YUV conversions.

interlaced: Default false. Use interlaced layout for YV12 - YUY2/RGB chroma conversions.

AviSynth prior to v2.50 can deal internally with two color formats, RGB and YUY2. Starting from v2.50 AviSynth can also deal with a third color format, YV12. These filters convert between them. If the video is already in the specified format, it will be passed through unchanged. RGB is assumed throughout this doc to mean RGBA = RGB32. ConvertToRGB converts to RGB32 unless your clip is RGB24. If you need 24-bit RGB for some reason, use ConvertToRGB24 explicitly and ConvertToRGB32 to do the reverse.

Syntax and operation of ConvertToRGB24 is identical to ConvertToRGB, except that the output format is 24-bit; if the source is RGB32, the alpha channel will be stripped.

Since v2.51/v2.52 an optional interlaced parameter is added (interlaced=false is the default operation). When set to false it is assumed that clip is progressive, when set to true it is assumed that clip is interlaced. This option is added because for example (assuming clip is interlaced YV12):

is upsampled incorrectly. Instead it is better to use:
ConvertToYV12(clip, interlaced=true)
Note, the interlaced=true setting only does something if the conversion YV12 <-> YUY2/RGB is requested, otherwise it's simply ignored. More about it can be found here "Color conversions and interlaced / field-based video".

Contrary to what one might expect, there is no unique way of converting YUV to RGB. In AviSynth the two most common ones are implemented: Rec.601 and Rec.709 (named after their official specifications). Although it will not be correct in all cases, the following shoud be correct in most cases:

The first one (Rec.601) should be used when your source is DivX/XviD or some analogue capture:


The second one (Rec.709) should be used when your source is DVD or HDTV:

ConvertToRGB(clip, matrix="rec709")

In v2.56, the reverse is also available, that is

ConvertToYUY2(clip, matrix="rec709") or ConvertToYV12(clip, matrix="rec709")

In v2.56, matrix="pc.601" (and matrix="pc.709") enables you to do the RGB <-> YUV conversion while keeping the luma range, thus RGB [0,255] <-> YUV [0,255] (instead of the usual/default RGB [0,255] <-> YUV [16,235]).

All VirtualDub filters (loaded with LoadVirtualdubPlugin, see Plugins) support only RGB32 input.

RGB24, RGB32: The colors are stored as values of red, green and blue. In RGB32 there is an extra Alpha channel for opacity. The image dimensions can have any values.

YUY2: The picture is stored as a luma value Y and two color values U, V. For two horizontal pixels there is only one chroma value and two luma values (two Y's, one U, one V). Therefore the width has to be a multiple of two.

YV12: The same as YUY2 but there is only one chroma value for 4 pixels (a 2x2 square). Both image dimensions have to be a multiple of two, if the video is interlaced the height has to be a multiple of four because the 2x2 square is taken from a field, not from a frame.

Some functions check for the dimension rules, some round the parameters, there still can be some where an picture distortion or an error occurs.

Working in YUY2 is faster than in RGB. YV12 is even faster and is the native MPEG format, so there are fewer colorspace conversions.

Conversion back and forth is not lossless, so use as few conversions as possible. If multiple conversions are necessary, use ConvertBackToYUY2 to convert to YUY2, if your source already has already once been YUY2. This will reduce colorblurring, but there is still some precision lost.

In most cases, the ConvertToRGB filter should not be necessary. If Avisynth's output is in YUY2 format and an application expects RGB, the system will use the installed YUY2 codec to make the conversion. However, if there's no installed YUY2 codec, or if (as is the case with ATI's and some other YUY2 codec) the codec converts from YUY2 to RGB incorrectly, you can use AviSynth's built-in filter to convert instead.

Huffyuv will act as the system YUY2 codec if there's no other codec installed, so if you install Huffyuv and uninstall all other YUY2 codecs, then you'll never need ConvertToRGB.

ConvertToRGB24 and ConvertToRGB32 can be used to force AviSynth to use a specific store method for RGB data. RGB24 data is often much slower to process than RGB32 data, so if your source is RGB24, you may get a speed gain by converting to RGB32. There are no known advantages of using RGB24 except that TMPGEnc and VFApi requires RGB24 input).

 # There is a slight distortion caused by the conversion between YUV and RGB.
# Let's see if we can see it.
control = ConvertToYUY2()
test = ConvertToYUY2(ConvertToRGB(ConvertToYUY2(ConvertToRGB(control))))
test = ConvertToYUY2(ConvertToRGB(test))
return Subtract(test,control)

$Date: 2006/09/27 18:41:25 $