boundary. Input devices may write padding bytes, the value is
undefined. Output devices ignore the contents of padding
bytes.</para><para>When the image format is planar the
-<structfield>bytesperline</structfield> value applies to the largest
+<structfield>bytesperline</structfield> value applies to the first
plane and is divided by the same factor as the
-<structfield>width</structfield> field for any smaller planes. For
+<structfield>width</structfield> field for the other planes. For
example the Cb and Cr planes of a YUV 4:2:0 image have half as many
padding bytes following each line as the Y plane. To avoid ambiguities
drivers must return a <structfield>bytesperline</structfield> value
</entry>
</row>
<row>
- <entry>__u16</entry>
+ <entry>__u32</entry>
<entry><structfield>bytesperline</structfield></entry>
<entry>Distance in bytes between the leftmost pixels in two adjacent
lines. See &v4l2-pix-format;.</entry>
</row>
<row>
<entry>__u16</entry>
- <entry><structfield>reserved[7]</structfield></entry>
+ <entry><structfield>reserved[6]</structfield></entry>
<entry>Reserved for future extensions. Should be zeroed by the
application.</entry>
</row>
Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;)
to specify non-standard quantization methods. Most of the time only the colorspace
field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note
-that the default R'G'B' quantization is always full range for all colorspaces,
-so this won't be mentioned explicitly for each colorspace description.</para>
+that the default R'G'B' quantization is full range for all colorspaces except for
+BT.2020 which uses limited range R'G'B' quantization.</para>
<table pgwide="1" frame="none" id="v4l2-colorspace">
<title>V4L2 Colorspaces</title>
<row>
<entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry>
<entry>Use the default quantization encoding as defined by the colorspace.
-This is always full range for R'G'B' and usually limited range for Y'CbCr.</entry>
+This is always full range for R'G'B' (except for the BT.2020 colorspace) and usually
+limited range for Y'CbCr.</entry>
</row>
<row>
<entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry>
<section>
<title>Detailed Colorspace Descriptions</title>
- <section>
- <title id="col-smpte-170m">Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title>
+ <section id="col-smpte-170m">
+ <title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title>
<para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV
in general. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and
<variablelist>
<varlistentry>
<term>The transfer function defined for SMPTE 170M is the same as the
-one defined in Rec. 709. Normally L is in the range [0…1], but for the extended
-gamut xvYCC encoding values outside that range are allowed.</term>
+one defined in Rec. 709.</term>
<listitem>
<para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para>
<para>L' = 4.5L for -0.018 < L < 0.018</para>
though BT.601 does not mention any color primaries.</para>
<para>The default quantization is limited range, but full range is possible although
rarely seen.</para>
- <para>The <constant>V4L2_YCBCR_ENC_601</constant> encoding as described above is the
-default for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_709</constant>,
-in which case the Rec. 709 Y'CbCr encoding is used.</para>
- <variablelist>
- <varlistentry>
- <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar
-to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range
-[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term>
- <listitem>
- <para>Y' = (219 / 255) * (0.299R' + 0.587G' + 0.114B') + (16 / 255)</para>
- <para>Cb = (224 / 255) * (-0.169R' - 0.331G' + 0.5B')</para>
- <para>Cr = (224 / 255) * (0.5R' - 0.419G' - 0.081B')</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped
-to the range [-0.5…0.5]. The non-standard xvYCC 709 encoding can also be used by selecting
-<constant>V4L2_YCBCR_ENC_XV709</constant>. The xvYCC encodings always use full range
-quantization.</para>
</section>
- <section>
- <title id="col-rec709">Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title>
+ <section id="col-rec709">
+ <title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title>
<para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default
Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is
limited range. The chromaticities of the primary colors and the white reference are:</para>
<para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default
for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which
case the BT.601 Y'CbCr encoding is used.</para>
+ <para>Two additional extended gamut Y'CbCr encodings are also possible with this colorspace:</para>
<variablelist>
<varlistentry>
<term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />)
is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range
[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term>
<listitem>
- <para>Y' = (219 / 255) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 255)</para>
- <para>Cb = (224 / 255) * (-0.1146R' - 0.3854G' + 0.5B')</para>
- <para>Cr = (224 / 255) * (0.5R' - 0.4542G' - 0.0458B')</para>
+ <para>Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)</para>
+ <para>Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')</para>
+ <para>Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar
+to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range
+[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term>
+ <listitem>
+ <para>Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)</para>
+ <para>Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')</para>
+ <para>Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')</para>
</listitem>
</varlistentry>
</variablelist>
<para>Y' is clamped to the range [0…1] and Cb and Cr are clamped
-to the range [-0.5…0.5]. The non-standard xvYCC 601 encoding can also be used by
-selecting <constant>V4L2_YCBCR_ENC_XV601</constant>. The xvYCC encodings always use full
-range quantization.</para>
+to the range [-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be used by
+selecting <constant>V4L2_YCBCR_ENC_XV709</constant> or <constant>V4L2_YCBCR_ENC_XV601</constant>.
+The xvYCC encodings always use full range quantization.</para>
</section>
- <section>
- <title id="col-srgb">Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title>
+ <section id="col-srgb">
+ <title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title>
<para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams and computer graphics. The
default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization
is full range. The chromaticities of the primary colors and the white reference are:</para>
values before quantization, but this encoding does not do that.</para>
</section>
- <section>
- <title id="col-adobergb">Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title>
+ <section id="col-adobergb">
+ <title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title>
<para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics
that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard.
The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr
SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para>
</section>
- <section>
- <title id="col-bt2020">Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title>
+ <section id="col-bt2020">
+ <title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title>
<para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition
television (UHDTV). The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>.
-The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and
-the white reference are:</para>
+The default R'G'B' quantization is limited range (!), and so is the default Y'CbCr quantization.
+The chromaticities of the primary colors and the white reference are:</para>
<table frame="none">
<title>BT.2020 Chromaticities</title>
<tgroup cols="3" align="left">
<term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term>
<listitem>
- <para>Y' = 0.2627R' + 0.6789G' + 0.0593B'</para>
+ <para>Y' = 0.2627R' + 0.6780G' + 0.0593B'</para>
<para>Cb = -0.1396R' - 0.3604G' + 0.5B'</para>
<para>Cr = 0.5R' - 0.4598G' - 0.0402B'</para>
</listitem>
<varlistentry>
<term>Luma:</term>
<listitem>
- <para>Yc' = (0.2627R + 0.6789G + 0.0593B)'</para>
+ <para>Yc' = (0.2627R + 0.6780G + 0.0593B)'</para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>B' - Yc' ≤ 0:</term>
<listitem>
- <para>Cbc = (B' - Y') / 1.9404</para>
+ <para>Cbc = (B' - Yc') / 1.9404</para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>B' - Yc' > 0:</term>
<listitem>
- <para>Cbc = (B' - Y') / 1.5816</para>
+ <para>Cbc = (B' - Yc') / 1.5816</para>
</listitem>
</varlistentry>
</variablelist>
clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para>
</section>
- <section>
- <title id="col-smpte-240m">Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title>
+ <section id="col-smpte-240m">
+ <title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title>
<para>The <xref linkend="smpte240m" /> standard was an interim standard used during the early days of HDTV (1988-1998).
It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>.
The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the
clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para>
</section>
- <section>
- <title id="col-sysm">Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title>
+ <section id="col-sysm">
+ <title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title>
<para>This standard defines the colorspace used by NTSC in 1953. In practice this
colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding
is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range.
This transform is identical to one defined in SMPTE 170M/BT.601.</para>
</section>
- <section>
- <title id="col-sysbg">Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title>
+ <section id="col-sysbg">
+ <title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title>
<para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this
colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding
is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range.
This transform is identical to one defined in SMPTE 170M/BT.601.</para>
</section>
- <section>
- <title id="col-jpeg">Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title>
+ <section id="col-jpeg">
+ <title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title>
<para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities
of the primary colors and the white reference are identical to sRGB. The Y'CbCr encoding is
<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where
projects / firefly-linux-kernel-4.4.55.git / blobdiff