Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/userspace-api/media/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _jpeg-controls:
  11
  12 **********************
  13 JPEG Control Reference
  14 **********************
  15
  16 The JPEG class includes controls for common features of JPEG encoders
  17 and decoders. Currently it includes features for codecs implementing
  18 progressive baseline DCT compression process with Huffman entrophy
  19 coding.
  20
  21
  22 .. _jpeg-control-id:
  23
  24 JPEG Control IDs
  25 ================
  26
  27 ``V4L2_CID_JPEG_CLASS (class)``
  28     The JPEG class descriptor. Calling
  29     :ref:`VIDIOC_QUERYCTRL` for this control will
  30     return a description of this control class.
  31
  32 ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
  33     The chroma subsampling factors describe how each component of an
  34     input image is sampled, in respect to maximum sample rate in each
  35     spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
  36     details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
  37     how Cb and Cr components are downsampled after converting an input
  38     image from RGB to Y'CbCr color space.
  39
  40 .. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
  41
  42 .. flat-table::
  43     :header-rows:  0
  44     :stub-columns: 0
  45
  46     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
  47       - No chroma subsampling, each pixel has Y, Cr and Cb values.
  48     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
  49       - Horizontally subsample Cr, Cb components by a factor of 2.
  50     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
  51       - Subsample Cr, Cb components horizontally and vertically by 2.
  52     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
  53       - Horizontally subsample Cr, Cb components by a factor of 4.
  54     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
  55       - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
  56     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
  57       - Use only luminance component.
  58
  59
  60
  61 ``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
  62     The restart interval determines an interval of inserting RSTm
  63     markers (m = 0..7). The purpose of these markers is to additionally
  64     reinitialize the encoder process, in order to process blocks of an
  65     image independently. For the lossy compression processes the restart
  66     interval unit is MCU (Minimum Coded Unit) and its value is contained
  67     in DRI (Define Restart Interval) marker. If
  68     ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
  69     markers will not be inserted.
  70
  71 .. _jpeg-quality-control:
  72
  73 ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
  74     ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
  75     between image quality and size. It provides simpler method for
  76     applications to control image quality, without a need for direct
  77     reconfiguration of luminance and chrominance quantization tables. In
  78     cases where a driver uses quantization tables configured directly by
  79     an application, using interfaces defined elsewhere,
  80     ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
  81     driver to 0.
  82
  83     The value range of this control is driver-specific. Only positive,
  84     non-zero values are meaningful. The recommended range is 1 - 100,
  85     where larger values correspond to better image quality.
  86
  87 .. _jpeg-active-marker-control:
  88
  89 ``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
  90     Specify which JPEG markers are included in compressed stream. This
  91     control is valid only for encoders.
  92
  93
  94
  95 .. flat-table::
  96     :header-rows:  0
  97     :stub-columns: 0
  98
  99     * - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
 100       - Application data segment APP\ :sub:`0`.
 101     * - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
 102       - Application data segment APP\ :sub:`1`.
 103     * - ``V4L2_JPEG_ACTIVE_MARKER_COM``
 104       - Comment segment.
 105     * - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
 106       - Quantization tables segment.
 107     * - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
 108       - Huffman tables segment.
 109
 110
 111
 112 For more details about JPEG specification, refer to :ref:`itu-t81`,
 113 :ref:`jfif`, :ref:`w3c-jpeg-jfif`.