Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 29fa0eed authored by Sylwester Nawrocki's avatar Sylwester Nawrocki Committed by Mauro Carvalho Chehab
Browse files

[media] V4L: Add JPEG compression control class documentation 



Add DocBook entries for the JPEG control class.

Signed-off-by: default avatarSylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: default avatarKyungmin Park <kyungmin.park@samsung.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent c7361ae1

Documentation/DocBook/media/v4l/biblio.xml

+20 −0
Original line number Diff line number Diff line
@@ -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>

Documentation/DocBook/media/v4l/compat.xml

+10 −0
Original line number Diff line number Diff line
@@ -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>

Documentation/DocBook/media/v4l/controls.xml

+161 −0
Original line number Diff line number Diff line
@@ -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>

Documentation/DocBook/media/v4l/v4l2.xml

+9 −0
Original line number Diff line number Diff line
@@ -127,6 +127,15 @@ structs, ioctls) must be noted in more detail in the history chapter 
(compat.xml), along with the possible impact on existing drivers and

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>

Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml

+14 −2
Original line number Diff line number Diff line
@@ -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>