diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/pixfmt.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/pixfmt.xml | 240 |
1 files changed, 158 insertions, 82 deletions
diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 5e0352c50324..965ea916784a 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -80,9 +80,9 @@ padding bytes after the last line of an image cross a system page 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 @@ -157,6 +157,14 @@ see <xref linkend="colorspaces" />.</entry> capture streams and by the application for output streams, see <xref linkend="colorspaces" />.</entry> </row> + <row> + <entry>&v4l2-xfer-func;</entry> + <entry><structfield>xfer_func</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> </tbody> </tgroup> </table> @@ -182,16 +190,16 @@ see <xref linkend="colorspaces" />.</entry> </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>Reserved for future extensions. Should be zeroed by the - application.</entry> + <entry><structfield>reserved[6]</structfield></entry> + <entry>Reserved for future extensions. Should be zeroed by drivers and + applications.</entry> </row> </tbody> </tgroup> @@ -264,11 +272,19 @@ see <xref linkend="colorspaces" />.</entry> capture streams and by the application for output streams, see <xref linkend="colorspaces" />.</entry> </row> + <row> + <entry>&v4l2-xfer-func;</entry> + <entry><structfield>xfer_func</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> <row> <entry>__u8</entry> - <entry><structfield>reserved[8]</structfield></entry> - <entry>Reserved for future extensions. Should be zeroed by the - application.</entry> + <entry><structfield>reserved[7]</structfield></entry> + <entry>Reserved for future extensions. Should be zeroed by drivers + and applications.</entry> </row> </tbody> </tgroup> @@ -476,15 +492,16 @@ is also very useful.</para> <section> <title>Defining Colorspaces in V4L2</title> - <para>In V4L2 colorspaces are defined by three values. The first is the colorspace -identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer + <para>In V4L2 colorspaces are defined by four values. The first is the colorspace +identifier (&v4l2-colorspace;) which defines the chromaticities, the default transfer function, the default Y'CbCr encoding and the default quantization method. The second -is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) to specify non-standard -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> +is the transfer function identifier (&v4l2-xfer-func;) to specify non-standard +transfer functions. The third is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) +to specify non-standard Y'CbCr encodings and the fourth 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 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> @@ -498,6 +515,11 @@ so this won't be mentioned explicitly for each colorspace description.</para> </thead> <tbody valign="top"> <row> + <entry><constant>V4L2_COLORSPACE_DEFAULT</constant></entry> + <entry>The default colorspace. This can be used by applications to let the + driver fill in the colorspace.</entry> + </row> + <row> <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> <entry>See <xref linkend="col-smpte-170m" />.</entry> </row> @@ -533,6 +555,52 @@ so this won't be mentioned explicitly for each colorspace description.</para> <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> <entry>See <xref linkend="col-jpeg" />.</entry> </row> + <row> + <entry><constant>V4L2_COLORSPACE_RAW</constant></entry> + <entry>The raw colorspace. This is used for raw image capture where + the image is minimally processed and is using the internal colorspace + of the device. The software that processes an image using this + 'colorspace' will have to know the internals of the capture device.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-xfer-func"> + <title>V4L2 Transfer Function</title> + <tgroup cols="2" align="left"> + &cs-def; + <thead> + <row> + <entry>Identifier</entry> + <entry>Details</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_XFER_FUNC_DEFAULT</constant></entry> + <entry>Use the default transfer function as defined by the colorspace.</entry> + </row> + <row> + <entry><constant>V4L2_XFER_FUNC_709</constant></entry> + <entry>Use the Rec. 709 transfer function.</entry> + </row> + <row> + <entry><constant>V4L2_XFER_FUNC_SRGB</constant></entry> + <entry>Use the sRGB transfer function.</entry> + </row> + <row> + <entry><constant>V4L2_XFER_FUNC_ADOBERGB</constant></entry> + <entry>Use the AdobeRGB transfer function.</entry> + </row> + <row> + <entry><constant>V4L2_XFER_FUNC_SMPTE240M</constant></entry> + <entry>Use the SMPTE 240M transfer function.</entry> + </row> + <row> + <entry><constant>V4L2_XFER_FUNC_NONE</constant></entry> + <entry>Do not use a transfer function (i.e. use linear RGB values).</entry> + </row> </tbody> </tgroup> </table> @@ -598,7 +666,8 @@ so this won't be mentioned explicitly for each colorspace description.</para> <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> @@ -620,10 +689,11 @@ is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to [16 <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>. +in general. The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. +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 the white reference are:</para> <table frame="none"> @@ -666,8 +736,7 @@ as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</par <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> @@ -702,30 +771,12 @@ defined in the <xref linkend="itu601" /> standard and this colorspace is sometim 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> - <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default + <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 transfer function is <constant>V4L2_XFER_FUNC_709</constant>. 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> <table frame="none"> @@ -803,29 +854,44 @@ rarely seen.</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> - <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> + <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 transfer function is <constant>V4L2_XFER_FUNC_SRGB</constant>. +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> <table frame="none"> <title>sRGB Chromaticities</title> <tgroup cols="3" align="left"> @@ -898,10 +964,11 @@ encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and of 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 transfer function is <constant>V4L2_XFER_FUNC_ADOBERGB</constant>. 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 the white reference are:</para> @@ -970,12 +1037,13 @@ clamped to the range [-0.5…0.5]. This transform is identical to one defin 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> +television (UHDTV). The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. +The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>. +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"> @@ -1032,7 +1100,7 @@ the white reference are:</para> <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> @@ -1046,7 +1114,7 @@ clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range <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> @@ -1054,7 +1122,7 @@ clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range <varlistentry> <term>B' - Yc' ≤ 0:</term> <listitem> - <para>Cbc = (B' - Y') / 1.9404</para> + <para>Cbc = (B' - Yc') / 1.9404</para> </listitem> </varlistentry> </variablelist> @@ -1062,7 +1130,7 @@ clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range <varlistentry> <term>B' - Yc' > 0:</term> <listitem> - <para>Cbc = (B' - Y') / 1.5816</para> + <para>Cbc = (B' - Yc') / 1.5816</para> </listitem> </varlistentry> </variablelist> @@ -1086,10 +1154,12 @@ clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range 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> - <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>. + <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 transfer function is <constant>V4L2_XFER_FUNC_SMPTE240M</constant>. +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 white reference are:</para> <table frame="none"> @@ -1159,11 +1229,13 @@ following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term> 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. +colorspace is obsolete and SMPTE 170M should be used instead. +The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. +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 the white reference are:</para> <table frame="none"> <title>NTSC 1953 Chromaticities</title> @@ -1237,11 +1309,13 @@ clamped to the range [-0.5…0.5]. The 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. +colorspace is obsolete and SMPTE 170M should be used instead. +The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. +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 the white reference are:</para> <table frame="none"> <title>EBU Tech. 3213 Chromaticities</title> @@ -1311,10 +1385,11 @@ clamped to the range [-0.5…0.5]. The 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 +of the primary colors and the white reference are identical to sRGB. The transfer +function use is <constant>V4L2_XFER_FUNC_SRGB</constant>. The Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and then clipped to [-128…127].</para> @@ -1435,6 +1510,7 @@ information.</para> &sub-y12; &sub-y10b; &sub-y16; + &sub-y16-be; &sub-uv8; &sub-yuyv; &sub-uyvy; |