[media] V4L: Add JPEG compression control class documentation
Add DocBook entries for the JPEG control class.
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: Kyungmin Park <kyungmin.park@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml
index cea6fd3..7dc65c5 100644
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ b/Documentation/DocBook/media/v4l/biblio.xml
@@ -128,6 +128,26 @@
<subtitle>Version 1.02</subtitle>
</biblioentry>
+ <biblioentry id="itu-t81">
+ <abbrev>ITU-T.81</abbrev>
+ <authorgroup>
+ <corpauthor>International Telecommunication Union
+(<ulink url="http://www.itu.int">http://www.itu.int</ulink>)</corpauthor>
+ </authorgroup>
+ <title>ITU-T Recommendation T.81
+"Information Technology — Digital Compression and Coding of Continous-Tone
+Still Images — Requirements and Guidelines"</title>
+ </biblioentry>
+
+ <biblioentry id="w3c-jpeg-jfif">
+ <abbrev>W3C JPEG JFIF</abbrev>
+ <authorgroup>
+ <corpauthor>The World Wide Web Consortium (<ulink
+url="http://www.w3.org/Graphics/JPEG">http://www.w3.org</ulink>)</corpauthor>
+ </authorgroup>
+ <title>JPEG JFIF</title>
+ </biblioentry>
+
<biblioentry id="smpte12m">
<abbrev>SMPTE 12M</abbrev>
<authorgroup>
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index c93298f..dd958b5 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2400,6 +2400,16 @@
</orderedlist>
</section>
+ <section>
+ <title>V4L2 in Linux 3.4</title>
+ <orderedlist>
+ <listitem>
+ <para>Added <link linkend="jpeg-controls">JPEG compression control
+ class</link>.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
<section id="other">
<title>Relation of V4L2 to other Linux multimedia APIs</title>
diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml
index 3f3d2e2..b84f25e 100644
--- a/Documentation/DocBook/media/v4l/controls.xml
+++ b/Documentation/DocBook/media/v4l/controls.xml
@@ -3436,6 +3436,167 @@
</tbody>
</tgroup>
</table>
+ </section>
+ <section id="jpeg-controls">
+ <title>JPEG Control Reference</title>
+ <para>The JPEG class includes controls for common features of JPEG
+ encoders and decoders. Currently it includes features for codecs
+ implementing progressive baseline DCT compression process with
+ Huffman entrophy coding.</para>
+ <table pgwide="1" frame="none" id="jpeg-control-id">
+ <title>JPEG Control IDs</title>
+
+ <tgroup cols="4">
+ <colspec colname="c1" colwidth="1*" />
+ <colspec colname="c2" colwidth="6*" />
+ <colspec colname="c3" colwidth="2*" />
+ <colspec colname="c4" colwidth="6*" />
+ <spanspec namest="c1" nameend="c2" spanname="id" />
+ <spanspec namest="c2" nameend="c4" spanname="descr" />
+ <thead>
+ <row>
+ <entry spanname="id" align="left">ID</entry>
+ <entry align="left">Type</entry>
+ </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row><entry></entry></row>
+ <row>
+ <entry spanname="id"><constant>V4L2_CID_JPEG_CLASS</constant> </entry>
+ <entry>class</entry>
+ </row><row><entry spanname="descr">The JPEG class descriptor. Calling
+ &VIDIOC-QUERYCTRL; for this control will return a description of this
+ control class.
+
+ </entry>
+ </row>
+ <row>
+ <entry spanname="id"><constant>V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant></entry>
+ <entry>menu</entry>
+ </row>
+ <row id="jpeg-chroma-subsampling-control">
+ <entry spanname="descr">The chroma subsampling factors describe how
+ each component of an input image is sampled, in respect to maximum
+ sample rate in each spatial dimension. See <xref linkend="itu-t81"/>,
+ clause A.1.1. for more details. The <constant>
+ V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant> control determines how
+ Cb and Cr components are downsampled after coverting an input image
+ from RGB to Y'CbCr color space.
+ </entry>
+ </row>
+ <row>
+ <entrytbl spanname="descr" cols="2">
+ <tbody valign="top">
+ <row>
+ <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_444</constant>
+ </entry><entry>No chroma subsampling, each pixel has
+ Y, Cr and Cb values.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_422</constant>
+ </entry><entry>Horizontally subsample Cr, Cb components
+ by a factor of 2.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_420</constant>
+ </entry><entry>Subsample Cr, Cb components horizontally
+ and vertically by 2.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_411</constant>
+ </entry><entry>Horizontally subsample Cr, Cb components
+ by a factor of 4.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_410</constant>
+ </entry><entry>Subsample Cr, Cb components horizontally
+ by 4 and vertically by 2.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY</constant>
+ </entry><entry>Use only luminance component.</entry>
+ </row>
+ </tbody>
+ </entrytbl>
+ </row>
+ <row>
+ <entry spanname="id"><constant>V4L2_CID_JPEG_RESTART_INTERVAL</constant>
+ </entry><entry>integer</entry>
+ </row>
+ <row><entry spanname="descr">
+ The restart interval determines an interval of inserting RSTm
+ markers (m = 0..7). The purpose of these markers is to additionally
+ reinitialize the encoder process, in order to process blocks of
+ an image independently.
+ For the lossy compression processes the restart interval unit is
+ MCU (Minimum Coded Unit) and its value is contained in DRI
+ (Define Restart Interval) marker. If <constant>
+ V4L2_CID_JPEG_RESTART_INTERVAL</constant> control is set to 0,
+ DRI and RSTm markers will not be inserted.
+ </entry>
+ </row>
+ <row id="jpeg-quality-control">
+ <entry spanname="id"><constant>V4L2_CID_JPEG_COMPRESION_QUALITY</constant></entry>
+ <entry>integer</entry>
+ </row>
+ <row>
+ <entry spanname="descr">
+ <constant>V4L2_CID_JPEG_COMPRESION_QUALITY</constant> control
+ determines trade-off between image quality and size.
+ It provides simpler method for applications to control image quality,
+ without a need for direct reconfiguration of luminance and chrominance
+ quantization tables.
+
+ In cases where a driver uses quantization tables configured directly
+ by an application, using interfaces defined elsewhere, <constant>
+ V4L2_CID_JPEG_COMPRESION_QUALITY</constant> control should be set
+ by driver to 0.
+
+ <para>The value range of this control is driver-specific. Only
+ positive, non-zero values are meaningful. The recommended range
+ is 1 - 100, where larger values correspond to better image quality.
+ </para>
+ </entry>
+ </row>
+ <row id="jpeg-active-marker-control">
+ <entry spanname="id"><constant>V4L2_CID_JPEG_ACTIVE_MARKER</constant></entry>
+ <entry>bitmask</entry>
+ </row>
+ <row>
+ <entry spanname="descr">Specify which JPEG markers are included
+ in compressed stream. This control is valid only for encoders.
+ </entry>
+ </row>
+ <row>
+ <entrytbl spanname="descr" cols="2">
+ <tbody valign="top">
+ <row>
+ <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP0</constant></entry>
+ <entry>Application data segment APP<subscript>0</subscript>.</entry>
+ </row><row>
+ <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP1</constant></entry>
+ <entry>Application data segment APP<subscript>1</subscript>.</entry>
+ </row><row>
+ <entry><constant>V4L2_JPEG_ACTIVE_MARKER_COM</constant></entry>
+ <entry>Comment segment.</entry>
+ </row><row>
+ <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DQT</constant></entry>
+ <entry>Quantization tables segment.</entry>
+ </row><row>
+ <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DHT</constant></entry>
+ <entry>Huffman tables segment.</entry>
+ </row>
+ </tbody>
+ </entrytbl>
+ </row>
+ <row><entry></entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>For more details about JPEG specification, refer
+ to <xref linkend="itu-t81"/>, <xref linkend="jfif"/>,
+ <xref linkend="w3c-jpeg-jfif"/>.</para>
</section>
</section>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index dcf9e33..8ae3887 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -128,6 +128,15 @@
applications. -->
<revision>
+ <revnumber>3.4</revnumber>
+ <date>2012-01-25</date>
+ <authorinitials>sn</authorinitials>
+ <revremark>Added <link linkend="jpeg-controls">JPEG compression
+ control class.</link>
+ </revremark>
+ </revision>
+
+ <revision>
<revnumber>3.3</revnumber>
<date>2012-01-11</date>
<authorinitials>hv</authorinitials>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml b/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml
index 01ea24b..4874849 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml
@@ -57,6 +57,11 @@
<refsect1>
<title>Description</title>
+ <para>These ioctls are <emphasis role="bold">deprecated</emphasis>.
+ New drivers and applications should use <link linkend="jpeg-controls">
+ JPEG class controls</link> for image quality and JPEG markers control.
+ </para>
+
<para>[to do]</para>
<para>Ronald Bultje elaborates:</para>
@@ -86,7 +91,10 @@
<row>
<entry>int</entry>
<entry><structfield>quality</structfield></entry>
- <entry></entry>
+ <entry>Deprecated. If <link linkend="jpeg-quality-control"><constant>
+ V4L2_CID_JPEG_IMAGE_QUALITY</constant></link> control is exposed by
+ a driver applications should use it instead and ignore this field.
+ </entry>
</row>
<row>
<entry>int</entry>
@@ -116,7 +124,11 @@
<row>
<entry>__u32</entry>
<entry><structfield>jpeg_markers</structfield></entry>
- <entry>See <xref linkend="jpeg-markers" />.</entry>
+ <entry>See <xref linkend="jpeg-markers"/>. Deprecated.
+ If <link linkend="jpeg-active-marker-control"><constant>
+ V4L2_CID_JPEG_ACTIVE_MARKER</constant></link> control
+ is exposed by a driver applications should use it instead
+ and ignore this field.</entry>
</row>
</tbody>
</tgroup>