[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 (file)
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ b/Documentation/DocBook/media/v4l/biblio.xml
@@ -128,6 +128,26 @@ url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor>
       <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 &mdash; Digital Compression and Coding of Continous-Tone
+Still Images &mdash; 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&nbsp;12M</abbrev>
       <authorgroup>

diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index c93298f..dd958b5 100644 (file)
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2400,6 +2400,16 @@ details.</para>
       </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 (file)
--- a/Documentation/DocBook/media/v4l/controls.xml
+++ b/Documentation/DocBook/media/v4l/controls.xml
@@ -3436,6 +3436,167 @@ interface and may change in the future.</para>
        </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>&nbsp;</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 (file)
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -128,6 +128,15 @@ structs, ioctls) must be noted in more detail in the history chapter
 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 (file)
--- 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 @@ to add them.</para>
          <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 @@ to add them.</para>
          <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>