ext-ctrls-jpeg.rst

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