From e2bb7f42681574ba3d64053cc6e06f621b23ab3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferenc=20Pint=C3=A9r?= Date: Wed, 18 Dec 2024 14:42:41 +0100 Subject: [PATCH] rst online docs: refresh ConvertToXXXX content --- .../avisynthdoc/corefilters/convert.rst | 574 ++++++++++++------ 1 file changed, 391 insertions(+), 183 deletions(-) diff --git a/distrib/docs/english/source/avisynthdoc/corefilters/convert.rst b/distrib/docs/english/source/avisynthdoc/corefilters/convert.rst index 0a66ec6b5..4f476fb9c 100644 --- a/distrib/docs/english/source/avisynthdoc/corefilters/convert.rst +++ b/distrib/docs/english/source/avisynthdoc/corefilters/convert.rst @@ -1,201 +1,399 @@ -ConvertBackToYUY2 / ConvertToRGB / ConvertToRGB24 / ConvertToRGB32 / ConvertToY8 / ConvertToYUY2 / ConvertToYV12 / ConvertToYV16 / ConvertToYV24 / ConvertToYV411 -================================================================================================================================================================= - -| ``ConvertToRGB`` (clip [, string "matrix"] [, bool "interlaced"] [, string - "ChromaInPlacement"] [, string "chromaresample"]) -| ``ConvertToRGB24`` (clip [, string "matrix"] [, bool "interlaced"] [, string - "ChromaInPlacement"] [, string "chromaresample"]) -| ``ConvertToRGB32`` (clip [, string "matrix"] [, bool "interlaced"] [, string - "ChromaInPlacement"] [, string "chromaresample"]) -| ``ConvertToYUY2`` (clip [, bool "interlaced"] [, string "matrix"] [, string - "ChromaInPlacement"] [, string "chromaresample"])`` -| ``ConvertBackToYUY2`` (clip [, string "matrix"]) -| ``ConvertToY8`` (clip [, string "matrix"]) -| ``ConvertToYV411`` (clip [, bool "interlaced"] [, string "matrix"] [, string - "ChromaInPlacement"] [, string "chromaresample"]) -| ``ConvertToYV12`` (clip [, bool "interlaced"] [, string "matrix"] [, string - "ChromaInPlacement"] [, string "chromaresample"] [, string - "ChromaOutPlacement"]) -| ``ConvertToYV16`` (clip [, bool "interlaced"] [, string "matrix"] [, string - "ChromaInPlacement"] [, string "chromaresample"]) -| ``ConvertToYV24`` (clip [, bool "interlaced"] [, string "matrix"] [, string - "ChromaInPlacement"] [, string "chromaresample"]) - - -Colorformats ------------- +ConvertToXXXX function +====================== + +*RGB interleaved* +:: + + ConvertToRGB(clip [, string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + + ConvertToRGB24(clip [, string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + + ConvertToRGB32(clip [, string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + + ConvertToRGB48(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3 ] ) + + ConvertToRGB64(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3 ] ) + + +*RGB planar* +:: + + ConvertToPlanarRGB(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample ] ) + ConvertToPlanarRGBA(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3 ] ) + + +*YUV444, YUVA444* +:: + + ConvertToYV24(clip [, bool interlaced, string matrix, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + ConvertToYUV444(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + ConvertToYUVA444(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + + +*YUV422, YUVA422* +:: + + ConvertToYV16(clip [, bool interlaced, string matrix, + string ChromaInPlacement, + string chromaresample, + string ChromaOutPlacement + float param1, float param2, float param3] ) + ConvertToYUV422(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + string ChromaOutPlacement, + float param1, float param2, float param3] ) + ConvertToYUVA422(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + string ChromaOutPlacement, + float param1, float param2, float param3] ) + +*YUY2* +:: + + ConvertToYUY2(clip [, bool interlaced, string matrix, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + ConvertBackToYUY2(clip [, string matrix ] ) + + +*YUV420, YUVA420* +:: + + ConvertToYV12(clip [, bool interlaced, string matrix, + string ChromaInPlacement, + string chromaresample, + string ChromaOutPlacement, + float param1, float param2, float param3] ) + ConvertToYUV420(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + string ChromaOutPlacement, + float param1, float param2, float param3] ) + ConvertToYUVA420(clip, [ string matrix, bool interlaced, + string ChromaInPlacement, + string chromaresample, + string ChromaOutPlacement, + float param1, float param2, float param3] ) + + +*YUV411* +:: + + ConvertToYV411(clip [, bool interlaced, string matrix, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + ConvertToYUV411(clip [, bool interlaced, string matrix, + string ChromaInPlacement, + string chromaresample, + float param1, float param2, float param3] ) + +(the 2nd one is just an alias) + +*Y-only* +:: + + ConvertToY8(clip [, string matrix] ) + ConvertToY(clip, [ string matrix ] ) + + +Color formats +------------- The following formats can be converted to and from. -+--------------+--------------------+------------------------------------------+ -| colorformats | planar/interleaved | chroma resolution | -+==============+====================+==========================================+ -| RGB | interleaved | full chroma - 4:4:4 | -+--------------+--------------------+------------------------------------------+ -| RGB24 | interleaved | full chroma - 4:4:4 | -+--------------+--------------------+------------------------------------------+ -| RGB32 | interleaved | full chroma - 4:4:4 | -+--------------+--------------------+------------------------------------------+ -| YUY2 | planar | chroma shared between 2 pixels - 4:2:2 | -+--------------+--------------------+------------------------------------------+ -| Y8 | planar/interleaved | no chroma - 4:0:0 | -+--------------+--------------------+------------------------------------------+ -| YV411 | planar | chroma shared between 4 pixels - 4:1:1 | -+--------------+--------------------+------------------------------------------+ -| YV12 | planar | chroma shared between 2x2 pixels - 4:2:0 | -+--------------+--------------------+------------------------------------------+ -| YV16 | planar | chroma shared between 2 pixels - 4:2:2 | -+--------------+--------------------+------------------------------------------+ -| YV24 | planar | full chroma - 4:4:4 | -+--------------+--------------------+------------------------------------------+ - -Options -------- - -*matrix*: Default Rec601. Controls the colour coefficients and scaling factors -used in RGB - YUV conversions. - -- "Rec601" : Uses Rec.601 coefficients, scaled to TV range [16,235]. -- "PC.601" : Uses Rec.601 coefficients, keep full range [0,255]. -- "Rec709" : Uses Rec.709 coefficients, scaled to TV range. -- "PC.709" : Uses Rec.709 coefficients, keep full range. -- "AVERAGE" : Uses averaged coefficients, keep full range (added in - *v2.60*). (So the luma becomes the average of the RGB channels.) - -*interlaced*: Default false. Use interlaced layout for YV12 chroma conversions. - -*ChromaInPlacement* (added in *v2.60*): This determines the chroma placement -when converting from YV12. It can be "MPEG2" (default), "MPEG1" and "DV". - -*chromaresample* (added in *v2.60*): This determines which resizer is used in -the conversion. It is used when the chroma resolution of the source and -target is different. It can be all resamplers, default is "bicubic". - -*ChromaOutPlacement* (added in *v2.60*): This determines the chroma placement -when converting to YV12. It can be "MPEG2" (default), "MPEG1" and "DV". - -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. - -In *v2.60* the following additional formats are supported: - -- Y8 greyscale (it is both planar and interleaved since it contains no chroma; 4:0:0) -- YV411 (planar; YUV 4:1:1) -- YV16 (a planar version of YUY2; 4:2:2) and -- YV24 (planar; YUV 4:4:4). +Notes: + +- Interleaved RGB formats (RGB24/32/48/64) are kept for compatibility, they come with fixed 8 and 16 bits. +- The successor RGB format is planar RGB/RGBA, which support any Avisynth+ high bit depth format. +- 8 bit YUV formats has their own old names, but can be written in the generic naming convention: + YV12=YUV420P8, YV16=YUV422P8, YV24=YUV444P8 +- If possible, avoid using YUY2 which is kept for compatibility. Use YV16 instead. + ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| Color formats | Bit depth | Sample ratio | Description | planar/ | +| | | | | interleaved | ++================+===========+==============+===============================================================+=============+ +| RGB24, RGB48 | 8, 16 | 4:4:4 | full chroma | interleaved | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| RGB32, RGB64 | 8, 16 | 4:4:4:4 | full chroma + alpha | interleaved | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| RGBPxx | 8-16, 32 | 4:4:4 | full chroma - known as planar RGB | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| RGBAPxx | 8-16, 32 | 4:4:4:4 | full chroma + alpha - known as planar RGBA | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YV24,YUV444Pxx | 8-16, 32 | 4:4:4 | full chroma | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YUVA444Pxx | 8-16, 32 | 4:4:4:4 | full chroma + alpha | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YV16,YUV422Pxx | 8-16, 32 | 4:2:2 | chroma shared between 2 pixels | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YUVA422Pxx | 8-16, 32 | 4:2:2:4 | chroma shared between 2 pixels + alpha | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YV12,YUV420Pxx | 8-16, 32 | 4:2:0 | chroma shared between 2x2 pixels | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YUVA420Pxx | 8-16, 32 | 4:2:0:4 | chroma shared between 2x2 pixels + alpha | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YV411,YUV411P8 | 8 | 4:1:1 | chroma shared between 4 pixels | planar | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| Y8,Y10-16,Y32 | 8-16, 32 | 4:0:0 | no chroma | both | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| YUY2 | 8 | 4:2:2 | chroma shared between 2 pixels. Deprecated format, use YV16 | interleaved | ++----------------+-----------+--------------+---------------------------------------------------------------+-------------+ +| xx refers to the bit depth, where | +| 8-16 = 8,10,12,14,16 bit integer; S or 32 is the 32 bit float. Use "S" in format names, except for Y, where Y32 is used.| ++----------------+-------------+-----------+--------------+---------------------------------------------------------------+ + +When the target format is the same as the source format, the original clip will be returned unchanged, +except for the cases where the ``ChromaInPlacement`` and ``ChromaOutPlacement`` parameters are different, +or the target placement is different from the source chroma placement read from ``_ChromaLocation`` frame property. + +Such functions are ``ConvertToYV12``/``ConvertToYUV420``/``ConvertToYUVA420`` or +``ConvertToYV16``/``ConvertToYUV422``/``ConvertToYUVA422``. + +Note ConvertToRGB always converts to RGB32 – unless your source is RGB24, in which case no conversion is done. +If you need 24-bit RGB for some reason, use ConvertToRGB24 explicitly. 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): -:: +Use ConvertBackToYUY2 to convert back to YUY2 with minimal color-blurring when you have previously applied a YUY2 -> RGB conversion. - SeparateFields(clip) - ConvertToYV12 +There is no unique way of converting YUV to RGB or vice-versa. There are different conversion matrices in use. +The following should be correct in most cases, see +`here `_ for more. -Weave is upsampled incorrectly. Instead it is better to use: -:: +- Rec.601 should be used when your source is standard definition (usually defined as smaller than 720p): + ``ConvertToRGB(clip) (using default "Rec601")`` - ConvertToYV12(clip, interlaced=true) +- Rec.709 should be used when your source is DVD or HDTV: + ``ConvertToRGB(clip, matrix="Rec709")`` -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 ":doc:`Color conversions and interlaced / field-based video <../advancedtopics/interlaced_fieldbased>`". +- The special-purpose matrices PC.601 and PC.709 keep the range unchanged (!), + instead of converting between 0d-255d RGB and 16d-235d YUV, as is the normal practice. + Note that if you want to convert from Y and no ``_ColorRange`` frame property present then it will treat it as + limited range. -When the target format is the same as the source format, the original clip -will be returned. Except for the following situation: When both formats are -YV12, the source clip will be processed when ChromaInPlacement and -ChromaOutPlacement differ. So this can be used to change the chroma placement -in a YV12 clip. +- The special-purpose matrix AVERAGE is used for (rarely found) sources with unweighted luma, + where ``Y = (R + G + B) / 3``. +How conversion detects whether full or limited (narrow range for RGB) conversion needed: -Examples --------- +- Avisynth can use the ``_ColorRange`` frame property to detect whether the source clip is of full or limited (narrow) range. +- If frame property ``_ColorRange`` is not present, then + + - ``full`` for RGB sources + - ``limited`` for YUV or Y (greyscale) sources + + is assumed. +- Along with frame properties, the matrix string can contain additional "hints", such as ``:f`` or ``:l``. +- When no other hint is given, some old-style Avisynth matrix name can specify limited/full: e.g. Rec.709 implies limited range. + Note: unlike ``PC.709`` or ``PC.601``: these matrix names do not force the clip being full or limited. -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: +See also: :doc:`ConvertBits ` to convert between bit depths and/or between full-limited range. -The first one (Rec.601) should be used when your source is DivX/XviD or some -analogue capture: -:: +Syntax and parameters +--------------------- - ConvertToRGB(clip) +.. describe:: matrix -The second one (Rec.709) should be used when your source is DVD or -HDTV: -:: + string matrix = "Rec601" - ConvertToRGB(clip, matrix="rec709") + Default "Rec601". Controls the colour coefficients and scaling factors used in RGB - YUV conversions. -In *v2.56*, the reverse is also available, that is + Old-style constants: -:: + - "Rec601" : Uses Rec.601 coefficients; scale full range [0d..255d] RGB ↔ TV range [16d..235d] YUV. + - "Rec709" : Uses Rec.709 (HD) coefficients; scale full range RGB ↔ TV range YUV. + - "Rec2020" : Uses Rec.2020 (UHD) coefficients; scale full range RGB ↔ TV range YUV. + - "PC.2020" : Uses Rec.2020 (UHD) coefficients; keep range unchanged. + - "PC.601" : Uses Rec.601 coefficients; keep range unchanged. + - "PC.709" : Uses Rec.709 (HD) coefficients; keep range unchanged. + - "Average" : Uses averaged coefficients (the luma becomes the average of the RGB channels); keep range unchanged. + + Additional matrix constants: + + New syntax: more matrix string constants with separate full/limited range markers. + ``"matrixname:full_or_limited"`` where + ``"matrixname"`` can be set as (for developers, internal _Matrix integer constant are given in parenthesys) + + - "rgb" (0 - AVS_MATRIX_RGB) + - "709" (1 - AVS_MATRIX_BT709) + - "unspec" (2 - AVS_MATRIX_UNSPECIFIED) + - "170m" (6 - AVS_MATRIX_ST170_M) + - "240m" (7 - AVS_MATRIX_ST240_M) + - "470bg" (5 - AVS_MATRIX_BT470_BG) + - "601" (5 - AVS_MATRIX_BT470_BG) + - "fcc" (4 - AVS_MATRIX_BT470_M) + - "bt470m" (4 - AVS_MATRIX_BT470_M) + - "ycgco" (8 - AVS_MATRIX_YCGCO not supported) + - "2020ncl" (9 - AVS_MATRIX_BT2020_NCL) + - "2020" (9 - AVS_MATRIX_BT2020_NCL) + - "2020cl" (10 - AVS_MATRIX_BT2020_CL same as 2020ncl) + - "chromacl" (13 - AVS_MATRIX_CHROMATICITY_DERIVED_CL not supported) + - "chromancl" (12 - AVS_MATRIX_CHROMATICITY_DERIVED_NCL not supported) + - "ictcp" (14 - AVS_MATRIX_ICTCP not supported) + + The above "matrix" parameters can be followed by a ``"full"`` or ``"f"`` and ``"limited"`` or ``"l"`` or + ``"auto"`` marker after a ``":"`` + + e.g. ``"709:l"`` means the same as the old "Rec709" + When there is no limited-ness marker, or is set to "auto" then value of _ColorRange frame property is used + + Note: old-style "matrix" parameters are kept, their name indicate the full/limited except ``"PC.601"`` and ``"PC.709"`` - ConvertToYUY2(clip, matrix="rec709") + For memo and the similar new string - or + "rec601" same as "470bg:l" + "rec709" "709:l" + "pc.601" and "pc601" "470bg:f" - but only if source has _ColorRange = 0 (full) + "pc.709" and "pc709" "709:f" - but only if source has _ColorRange = 0 (full) + "average" - kept for compatibility, really it has no standard _Matrix equivalent + "rec2020" "2020cl:l" + "pc.2020" and "pc2020" "2020cl:f" - but only if source has _ColorRange = 0 (full) - ConvertToYV12(clip, matrix="rec709") +.. describe:: interlaced -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]). + bool interlaced = false + + If true, it is assumed that clip is interlaced; by default, it is assumed to be progressive. + This option is needed because for example, the following (assuming clip is interlaced YV12): + :: -All VirtualDub filters (loaded with ``LoadVirtualdubPlugin``, see :ref:`Plugins `) -support only RGB32 input. + SeparateFields(clip) + ConvertToYV16 + Weave -**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. + ...is upsampled incorrectly. Instead it is better to use: + :: -**YV8:** Greyscale. Thus the same as YV24 without the chroma planes. + ConvertToYV16(clip, interlaced=true) -**YV411:** Similar as YV12 but with only one chroma value for 4 pixels (a 1x4 -square). The horizontal image dimension has to be a multiple of four. -**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. + Note, interlaced=true has an effect only on YV12 <-> YV16/YUY2 or YV12 <-> RGB conversions. + (and their high bit depth equivalents). + More about that can be found here: + :doc:`Color conversions and interlaced / field-based video <../advancedtopics/interlaced_fieldbased>`. -**YV16:** The same as YUY2 but planar instead of interleaved. +.. describe:: ChromaInPlacement, ChromaOutPlacement -**YV24:** The same as YV12/YV16, but with full chroma. + string ChromaInPlacement = "MPEG2" + + string ChromaOutPlacement = "MPEG2" -Some functions check for the dimension rules, some round the parameters, -there still can be some where an picture distortion or an error occurs. + ChromaInPlacement determines the chroma placement in the clip when converting from YV12/YUV420 or YV16/YUV422. + ChromaOutPlacement determines the chroma placement in the clip when converting to YV12/YUV420 or YV16/YUV422. + + The placement can be one of these strings: -Working in YUY2 is faster than in RGB. YV12 is even faster and is the native -MPEG format, so there are fewer colorspace conversions. + - ``"MPEG2"`` (synonyms: ``"left"``) + Subsampling used in MPEG-2 4:2:x and most other formats. Chroma samples are located on the left pixel column of the group (default). + - ``"MPEG1"`` (synonyms: ``"jpeg"``, ``"center"``) + Subsampling used in MPEG-1 4:2:0. Chroma samples are located on the center of each group of 4 pixels. + - ``"DV"`` + Like MPEG-2, but U and V channels are co-sited vertically: V on the top row, and U on the bottom row. For 4:1:1, chroma is located on the leftmost column. + - ``"top_left"`` + Subsampling used in UHD 4:2:0. Chroma samples are located on the top left pixel column of the group. + - ``bottom_left`` 4:2:0 only + - ``bottom`` 4:2:0 only -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. + See also the Frame properties section below. + + +.. describe:: chromaresample + + string chromaresample = "bicubic" + + Determines which chroma resampler is used in the conversion. Only used when the chroma resolutions + of the source and target are different. All AviSynth :doc:`resizers ` are allowed + ("point", "bilinear", "bicubic", "lanczos", "lanczos4", "blackman", "spline16", "spline36", "spline64", + "gauss" and "sinc", "sinpow", "sinclin2" and "userdefined2"). + + Default is "bicubic". + +.. describe:: param1, param2, param3 + + These 'float' type parameters can be the additional parameters for the chroma + resamplers. Some resizer algorithms would need and can be fine tuned with up to 3 parameters. + Their default values depend on the selected chromaresample resizer kernel, + + +Frame properties +---------------- + +Since Avisynth v3.7.1 frame property (_ChromaLocation) support appears in selected filters (e.g. ConvertToYUV422). +Property can be read and/or set. A frame property can replace default behaviour of location parameters and is set +(or deleted) upon finishing conversion. Since a format without subsampling - such as 4:4:4 (YV24) - does not have +chroma location, the property is deleted automatically when converting to YUV444 or RGB. + +- "ChromaInPlacement" rules: + + * if source has _ChromaLocation frame property it will be used else the default is "mpeg2" ("left") + * if parameter is "auto" or not given at all, ChromaInLocation will be set to the above mentioned default value + * if parameter is explicitely given, it will be used + +- "ChromaOutPlacement" rules: + + * default is "mpeg2" ("left") + * if parameter is "auto" or not given at all, ChromaOutLocation will be set to the above mentioned default value + * if parameter is explicitely given, it will be used + + Accepted values for "ChromaInPlacement" and "ChromaOutPlacement" (when source/target is a chroma subsampled format) + (full list): + + * "left" or "mpeg2" + * "center" or "jpeg" or "mpeg1" + * "top_left" + * "dv" + * "top" + * "bottom_left" + * "bottom" + +- _ChromaLocation constants - just for info: as seen in propShow + + * AVS_CHROMA_LEFT = 0 + * AVS_CHROMA_CENTER = 1 + * AVS_CHROMA_TOP_LEFT = 2 (4:2:0 only) + * AVS_CHROMA_TOP = 3 (4:2:0 only) + * AVS_CHROMA_BOTTOM_LEFT = 4 (4:2:0 only) + * AVS_CHROMA_BOTTOM = 5 (4:2:0 only) + * AVS_CHROMA_DV = 6 Special to Avisynth -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. Conversion paths ---------------- @@ -204,22 +402,20 @@ Conversion paths options are only used in the 'planar conversion part' of the conversion path, and they process the chroma of the clip. -In v2.60 the following conversion paths occur +The following conversion paths occur - YUV planar -> RGB via YV24 -- YUV planar -> YUY2 via YV16 (except for YV12 and parameters - *ChromaInPlacement*/*chromaresample* not explicitly set", in that case - there is a direct conversion from YV12 to YUY2) +- YUV planar -> YUY2 via YV16 - RGB -> YUV planar via YV24 -- YUY2 -> YUV planar via YV16 (except for YV12 and parameters - *ChromaInPlacement*/*chromaresample* not explicitly set", in that case - there is a direct conversion from YUY2 to YV12) +- YUY2 -> YUV planar via YV16 + +Suppose you have a YUY2 clip for example and you convert it to YV24. + +The YUY2 will be converted to YV16 first without applying *ChromaInPlacement*, +*chromaresample* and *ChromaOutPlacement*. -Suppose you have a YUY2 clip for example and you convert it to YV24. The YUY2 -will be converted to YV16 first without applying *ChromaInPlacement*, -*chromaresample* and *ChromaOutPlacement*. Then YV16 will be converted to -YV24 while applying *chromaresample*. *ChromaInPlacement* and -*ChromaOutPlacement* won't be used since YV12 is not involved. +Then YV16 will be converted to YV24 while applying *chromaresample*. +*ChromaOutPlacement* won't be used since our target is YV24. Sampling @@ -233,15 +429,27 @@ Color conversions :doc:`This page <../advancedtopics/color_conversions>` covers the color conversions, "YUV <-> RGB", in more detail. -+----------+-------------------------------------------+ -| Changes: | | -+==========+===========================================+ -| v2.60 | Added: ConvertToY8, ConvertToYV411, | -| | ConvertToYV16, ConvertToYV24, | -| | ChromaInPlacement, ChromaOutPlacement and | -| | chromaresample, matrix="AVERAGE" | -+----------+-------------------------------------------+ -| v2.50 | ConvertToYV12 | -+----------+-------------------------------------------+ - -$Date: 2011/12/04 15:28:44 $ ++----------+------------------------------------------------------------+ +| Changes: | | ++==========+============================================================+ +| v3.7.3 || Added "sinpow", "sinclin2" and "userdefined2" to | +| | chromaresampler options | +| || Add "param1", "param2" and "param3" to ConvertToXXXX where| +| | 'chromaresample' exists (b,c,s,taps and p parameters can | +| | be set, depending on the resizer.) | +| || Add ConvertToYUVA420, ConvertToYUVA422, ConvertToYUVA444 | ++----------+------------------------------------------------------------+ +| v3.7.1 || Added ChromaOutPlacement to 4:2:2 related functions | +| || Added new matrix constants, optional new syntax | +| || Added new chroma location constants | +| || Added _ChromaLocation frame property | ++----------+------------------------------------------------------------+ +| v2.60 || Added: ConvertToY8, ConvertToYV411, | +| | ConvertToYV16, ConvertToYV24, | +| || Added ChromaInPlacement, ChromaOutPlacement and | +| | chromaresample, matrix="AVERAGE" | ++----------+------------------------------------------------------------+ +| v2.50 | ConvertToYV12 | ++----------+------------------------------------------------------------+ + +$Date: 2024/12/18 13:23:00 $