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