Skip to content

L
linux
Commit 22b6ae48 authored by Hans Verkuil's avatar Hans Verkuil Committed by Mauro Carvalho Chehab
Browse files
Options

[media] DocBook/media: document new xfer_func fields 

Document the new field and defines to set the transfer function needed
to correctly decode the colors of an image.
Signed-off-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@osg.samsung.com>
parent 74fdcb2e
Hide whitespace changes
Inline Side-by-side
Showing with 101 additions and 24 deletions
Documentation/DocBook/media/v4l/pixfmt.xml
View file @ 22b6ae48
...@@ -155,6 +155,14 @@ see <xref linkend="colorspaces" />.</entry> ...@@ -155,6 +155,14 @@ see <xref linkend="colorspaces" />.</entry>
<entry>This information supplements the <entry>This information supplements the
<structfield>colorspace</structfield> and must be set by the driver for <structfield>colorspace</structfield> and must be set by the driver for
capture streams and by the application for output streams, 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> see <xref linkend="colorspaces" />.</entry>
</row> </row>
</tbody> </tbody>
...@@ -262,11 +270,19 @@ see <xref linkend="colorspaces" />.</entry> ...@@ -262,11 +270,19 @@ see <xref linkend="colorspaces" />.</entry>
<entry>This information supplements the <entry>This information supplements the
<structfield>colorspace</structfield> and must be set by the driver for <structfield>colorspace</structfield> and must be set by the driver for
capture streams and by the application for output streams, 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> see <xref linkend="colorspaces" />.</entry>
</row> </row>
<row> <row>
<entry>__u8</entry> <entry>__u8</entry>
<entry><structfield>reserved[8]</structfield></entry> <entry><structfield>reserved[7]</structfield></entry>
<entry>Reserved for future extensions. Should be zeroed by the <entry>Reserved for future extensions. Should be zeroed by the
application.</entry> application.</entry>
</row> </row>
...@@ -476,15 +492,16 @@ is also very useful.</para> ...@@ -476,15 +492,16 @@ is also very useful.</para>
<section> <section>
<title>Defining Colorspaces in V4L2</title> <title>Defining Colorspaces in V4L2</title>
<para>In V4L2 colorspaces are defined by three values. The first is the colorspace <para>In V4L2 colorspaces are defined by four values. The first is the colorspace
identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer identifier (&v4l2-colorspace;) which defines the chromaticities, the default transfer
function, the default Y'CbCr encoding and the default quantization method. The second 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 is the transfer function identifier (&v4l2-xfer-func;) to specify non-standard
Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;) transfer functions. The third is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;)
to specify non-standard quantization methods. Most of the time only the colorspace to specify non-standard Y'CbCr encodings and the fourth is the quantization identifier
field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note (&v4l2-quantization;) to specify non-standard quantization methods. Most of the time
that the default R'G'B' quantization is full range for all colorspaces except for only the colorspace field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to
BT.2020 which uses limited range R'G'B' quantization.</para> 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"> <table pgwide="1" frame="none" id="v4l2-colorspace">
<title>V4L2 Colorspaces</title> <title>V4L2 Colorspaces</title>
...@@ -549,6 +566,45 @@ BT.2020 which uses limited range R'G'B' quantization.</para> ...@@ -549,6 +566,45 @@ BT.2020 which uses limited range R'G'B' quantization.</para>
</tgroup> </tgroup>
</table> </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>
<table pgwide="1" frame="none" id="v4l2-ycbcr-encoding"> <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding">
<title>V4L2 Y'CbCr Encodings</title> <title>V4L2 Y'CbCr Encodings</title>
<tgroup cols="2" align="left"> <tgroup cols="2" align="left">
...@@ -636,7 +692,8 @@ is mapped to [16&hellip;235]. Cb and Cr are mapped from [-0.5&hellip;0.5] to [16 ...@@ -636,7 +692,8 @@ is mapped to [16&hellip;235]. Cb and Cr are mapped from [-0.5&hellip;0.5] to [16
<section id="col-smpte-170m"> <section id="col-smpte-170m">
<title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title> <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 <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 default Y'CbCr quantization is limited range. The chromaticities of the primary colors and
the white reference are:</para> the white reference are:</para>
<table frame="none"> <table frame="none">
...@@ -718,7 +775,8 @@ rarely seen.</para> ...@@ -718,7 +775,8 @@ rarely seen.</para>
<section id="col-rec709"> <section id="col-rec709">
<title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title> <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 <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 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> limited range. The chromaticities of the primary colors and the white reference are:</para>
<table frame="none"> <table frame="none">
...@@ -829,9 +887,11 @@ The xvYCC encodings always use full range quantization.</para> ...@@ -829,9 +887,11 @@ The xvYCC encodings always use full range quantization.</para>
<section id="col-srgb"> <section id="col-srgb">
<title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title> <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 <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams
default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization and computer graphics. The default transfer function is <constant>V4L2_XFER_FUNC_SRGB</constant>.
is full range. The chromaticities of the primary colors and the white reference are:</para> 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"> <table frame="none">
<title>sRGB Chromaticities</title> <title>sRGB Chromaticities</title>
<tgroup cols="3" align="left"> <tgroup cols="3" align="left">
...@@ -908,6 +968,7 @@ values before quantization, but this encoding does not do that.</para> ...@@ -908,6 +968,7 @@ values before quantization, but this encoding does not do that.</para>
<title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title> <title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title>
<para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics <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. 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 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 quantization is limited range. The chromaticities of the primary colors and the white reference
are:</para> are:</para>
...@@ -979,7 +1040,8 @@ SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para> ...@@ -979,7 +1040,8 @@ SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para>
<section id="col-bt2020"> <section id="col-bt2020">
<title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title> <title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title>
<para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition <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>. 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 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> The chromaticities of the primary colors and the white reference are:</para>
<table frame="none"> <table frame="none">
...@@ -1094,8 +1156,10 @@ clamped to the range [-0.5&hellip;0.5]. The Yc'CbcCrc quantization is limited ra ...@@ -1094,8 +1156,10 @@ clamped to the range [-0.5&hellip;0.5]. The Yc'CbcCrc quantization is limited ra
<section id="col-smpte-240m"> <section id="col-smpte-240m">
<title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> <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). <para>The <xref linkend="smpte240m" /> standard was an interim standard used during
It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>. 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 The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the
white reference are:</para> white reference are:</para>
<table frame="none"> <table frame="none">
...@@ -1168,8 +1232,10 @@ clamped to the range [-0.5&hellip;0.5]. The Y'CbCr quantization is limited range ...@@ -1168,8 +1232,10 @@ clamped to the range [-0.5&hellip;0.5]. The Y'CbCr quantization is limited range
<section id="col-sysm"> <section id="col-sysm">
<title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title> <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 <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 colorspace is obsolete and SMPTE 170M should be used instead.
is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. 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> The chromaticities of the primary colors and the white reference are:</para>
<table frame="none"> <table frame="none">
<title>NTSC 1953 Chromaticities</title> <title>NTSC 1953 Chromaticities</title>
...@@ -1246,8 +1312,10 @@ This transform is identical to one defined in SMPTE 170M/BT.601.</para> ...@@ -1246,8 +1312,10 @@ This transform is identical to one defined in SMPTE 170M/BT.601.</para>
<section id="col-sysbg"> <section id="col-sysbg">
<title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title> <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 <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 colorspace is obsolete and SMPTE 170M should be used instead.
is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. 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> The chromaticities of the primary colors and the white reference are:</para>
<table frame="none"> <table frame="none">
<title>EBU Tech. 3213 Chromaticities</title> <title>EBU Tech. 3213 Chromaticities</title>
...@@ -1320,7 +1388,8 @@ This transform is identical to one defined in SMPTE 170M/BT.601.</para> ...@@ -1320,7 +1388,8 @@ This transform is identical to one defined in SMPTE 170M/BT.601.</para>
<section id="col-jpeg"> <section id="col-jpeg">
<title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title> <title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title>
<para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities <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 <constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where
Y' is scaled to [0&hellip;255] and Cb/Cr are scaled to [-128&hellip;128] and Y' is scaled to [0&hellip;255] and Cb/Cr are scaled to [-128&hellip;128] and
then clipped to [-128&hellip;127].</para> then clipped to [-128&hellip;127].</para>
......
Documentation/DocBook/media/v4l/subdev-formats.xml
View file @ 22b6ae48
...@@ -50,8 +50,16 @@ capture streams and by the application for output streams, ...@@ -50,8 +50,16 @@ capture streams and by the application for output streams,
see <xref linkend="colorspaces" />.</entry> see <xref linkend="colorspaces" />.</entry>
</row> </row>
<row> <row>
<entry>__u32</entry> <entry>&v4l2-xfer-func;</entry>
<entry><structfield>reserved</structfield>[6]</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>__u16</entry>
<entry><structfield>reserved</structfield>[11]</entry>
<entry>Reserved for future extensions. Applications and drivers must <entry>Reserved for future extensions. Applications and drivers must
set the array to zero.</entry> set the array to zero.</entry>
</row> </row>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7