1 .. -*- coding: utf-8; mode: rst -*-
13 The control mechanism as originally designed was meant to be used for
14 user settings (brightness, saturation, etc). However, it turned out to
15 be a very useful model for implementing more complicated driver APIs
16 where each driver implements only a subset of a larger API.
18 The MPEG encoding API was the driving force behind designing and
19 implementing this extended control mechanism: the MPEG standard is quite
20 large and the currently supported hardware MPEG encoders each only
21 implement a subset of this standard. Further more, many parameters
22 relating to how the video is encoded into an MPEG stream are specific to
23 the MPEG encoding chip since the MPEG standard only defines the format
24 of the resulting MPEG stream, not how the video is actually encoded into
27 Unfortunately, the original control API lacked some features needed for
28 these new uses and so it was extended into the (not terribly originally
29 named) extended control API.
31 Even though the MPEG encoding API was the first effort to use the
32 Extended Control API, nowadays there are also other classes of Extended
33 Controls, such as Camera Controls and FM Transmitter Controls. The
34 Extended Controls API as well as all Extended Controls classes are
35 described in the following text.
38 The Extended Control API
39 ========================
41 Three new ioctls are available:
42 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
43 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
44 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act
45 on arrays of controls (as opposed to the
46 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
47 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single
48 control). This is needed since it is often required to atomically change
49 several controls at once.
51 Each of the new ioctls expects a pointer to a struct
52 :c:type:`v4l2_ext_controls`. This structure
53 contains a pointer to the control array, a count of the number of
54 controls in that array and a control class. Control classes are used to
55 group similar controls into a single class. For example, control class
56 ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
57 that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
58 ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls
59 relating to MPEG encoding, etc.
61 All controls in the control array must belong to the specified control
62 class. An error is returned if this is not the case.
64 It is also possible to use an empty control array (``count`` == 0) to check
65 whether the specified control class is supported.
67 The control array is a struct
68 :c:type:`v4l2_ext_control` array. The
69 struct :c:type:`v4l2_ext_control` is very similar to
70 struct :c:type:`v4l2_control`, except for the fact that
71 it also allows for 64-bit values and pointers to be passed.
73 Since the struct :c:type:`v4l2_ext_control` supports
74 pointers it is now also possible to have controls with compound types
75 such as N-dimensional arrays and/or structures. You need to specify the
76 ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
77 be able to see such compound controls. In other words, these controls
78 with compound types should only be used programmatically.
80 Since such compound controls need to expose more information about
81 themselves than is possible with
82 :ref:`VIDIOC_QUERYCTRL` the
83 :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
84 particular, this ioctl gives the dimensions of the N-dimensional array
85 if this control consists of more than one element.
89 #. It is important to realize that due to the flexibility of controls it is
90 necessary to check whether the control you want to set actually is
91 supported in the driver and what the valid range of values is. So use
92 the :ref:`VIDIOC_QUERYCTRL` (or :ref:`VIDIOC_QUERY_EXT_CTRL
93 <VIDIOC_QUERYCTRL>`) and :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`
96 #. It is possible that some of the menu indices in a control of
97 type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
98 will return an error). A good example is the list of supported MPEG
99 audio bitrates. Some drivers only support one or two bitrates, others
100 support a wider range.
102 All controls use machine endianness.
105 Enumerating Extended Controls
106 =============================
108 The recommended way to enumerate over the extended controls is by using
109 :ref:`VIDIOC_QUERYCTRL` in combination with the
110 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:
115 struct v4l2_queryctrl qctrl;
117 qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
118 while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
120 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
123 The initial control ID is set to 0 ORed with the
124 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
125 return the first control with a higher ID than the specified one. When
126 no such controls are found an error is returned.
128 If you want to get all controls within a specific control class, then
129 you can set the initial ``qctrl.id`` value to the control class and add
130 an extra check to break out of the loop when a control of another
131 control class is found:
136 qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
137 while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
138 if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
141 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
144 The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
145 top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
146 and are not actually part of the ID. The remaining 28 bits form the
147 control ID, of which the most significant 12 bits define the control
148 class and the least significant 16 bits identify the control within the
149 control class. It is guaranteed that these last 16 bits are always
150 non-zero for controls. The range of 0x1000 and up are reserved for
151 driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
152 the control class ID based on a control ID.
154 If the driver does not support extended controls, then
155 ``VIDIOC_QUERYCTRL`` will fail when used in combination with
156 ``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
157 control should be used (see :ref:`enum_all_controls`). But if it is
158 supported, then it is guaranteed to enumerate over all controls,
159 including driver-private controls.
162 Creating Control Panels
163 =======================
165 It is possible to create control panels for a graphical user interface
166 where the user can select the various controls. Basically you will have
167 to iterate over all controls using the method described above. Each
168 control class starts with a control of type
169 ``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
170 of this control class which can be used as the title of a tab page
171 within a control panel.
173 The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
174 contains hints on the behavior of the control. See the
175 :ref:`VIDIOC_QUERYCTRL` documentation for more
181 Codec Control Reference
182 =======================
184 Below all controls within the Codec control class are described. First
185 the generic controls, then controls specific for certain hardware.
189 These controls are applicable to all codecs and not just MPEG. The
190 defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
191 were originally made for MPEG codecs and later extended to cover all
195 Generic Codec Controls
196 ----------------------
204 ``V4L2_CID_MPEG_CLASS (class)``
205 The Codec class descriptor. Calling
206 :ref:`VIDIOC_QUERYCTRL` for this control will
207 return a description of this control class. This description can be
208 used as the caption of a Tab page in a GUI, for example.
210 .. _v4l2-mpeg-stream-type:
212 ``V4L2_CID_MPEG_STREAM_TYPE``
215 enum v4l2_mpeg_stream_type -
216 The MPEG-1, -2 or -4 output stream type. One cannot assume anything
217 here. Each hardware MPEG encoder tends to support different subsets
218 of the available MPEG stream types. This control is specific to
219 multiplexed MPEG streams. The currently defined stream types are:
227 * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS``
228 - MPEG-2 program stream
229 * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS``
230 - MPEG-2 transport stream
231 * - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS``
232 - MPEG-1 system stream
233 * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD``
234 - MPEG-2 DVD-compatible stream
235 * - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD``
236 - MPEG-1 VCD-compatible stream
237 * - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD``
238 - MPEG-2 SVCD-compatible stream
242 ``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
243 Program Map Table Packet ID for the MPEG transport stream (default
246 ``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
247 Audio Packet ID for the MPEG transport stream (default 256)
249 ``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
250 Video Packet ID for the MPEG transport stream (default 260)
252 ``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
253 Packet ID for the MPEG transport stream carrying PCR fields (default
256 ``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
257 Audio ID for MPEG PES
259 ``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
260 Video ID for MPEG PES
262 .. _v4l2-mpeg-stream-vbi-fmt:
264 ``V4L2_CID_MPEG_STREAM_VBI_FMT``
267 enum v4l2_mpeg_stream_vbi_fmt -
268 Some cards can embed VBI data (e. g. Closed Caption, Teletext) into
269 the MPEG stream. This control selects whether VBI data should be
270 embedded, and if so, what embedding method should be used. The list
271 of possible VBI formats depends on the driver. The currently defined
272 VBI format types are:
276 .. tabularcolumns:: |p{6 cm}|p{11.5cm}|
282 * - ``V4L2_MPEG_STREAM_VBI_FMT_NONE``
283 - No VBI in the MPEG stream
284 * - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
285 - VBI in private packets, IVTV format (documented in the kernel
287 ``Documentation/media/v4l-drivers/cx2341x.rst``)
291 .. _v4l2-mpeg-audio-sampling-freq:
293 ``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ``
296 enum v4l2_mpeg_audio_sampling_freq -
297 MPEG Audio sampling frequency. Possible values are:
305 * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
307 * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
309 * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
314 .. _v4l2-mpeg-audio-encoding:
316 ``V4L2_CID_MPEG_AUDIO_ENCODING``
319 enum v4l2_mpeg_audio_encoding -
320 MPEG Audio encoding. This control is specific to multiplexed MPEG
321 streams. Possible values are:
329 * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1``
330 - MPEG-1/2 Layer I encoding
331 * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2``
332 - MPEG-1/2 Layer II encoding
333 * - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3``
334 - MPEG-1/2 Layer III encoding
335 * - ``V4L2_MPEG_AUDIO_ENCODING_AAC``
336 - MPEG-2/4 AAC (Advanced Audio Coding)
337 * - ``V4L2_MPEG_AUDIO_ENCODING_AC3``
338 - AC-3 aka ATSC A/52 encoding
342 .. _v4l2-mpeg-audio-l1-bitrate:
344 ``V4L2_CID_MPEG_AUDIO_L1_BITRATE``
347 enum v4l2_mpeg_audio_l1_bitrate -
348 MPEG-1/2 Layer I bitrate. Possible values are:
356 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
358 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
360 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
362 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
364 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
366 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
368 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
370 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
372 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
374 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
376 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
378 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
380 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
382 * - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
387 .. _v4l2-mpeg-audio-l2-bitrate:
389 ``V4L2_CID_MPEG_AUDIO_L2_BITRATE``
392 enum v4l2_mpeg_audio_l2_bitrate -
393 MPEG-1/2 Layer II bitrate. Possible values are:
401 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
403 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
405 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
407 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
409 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
411 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
413 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
415 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
417 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
419 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
421 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
423 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
425 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
427 * - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
432 .. _v4l2-mpeg-audio-l3-bitrate:
434 ``V4L2_CID_MPEG_AUDIO_L3_BITRATE``
437 enum v4l2_mpeg_audio_l3_bitrate -
438 MPEG-1/2 Layer III bitrate. Possible values are:
446 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
448 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
450 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
452 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
454 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
456 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
458 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
460 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
462 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
464 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
466 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
468 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
470 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
472 * - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
477 ``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
478 AAC bitrate in bits per second.
480 .. _v4l2-mpeg-audio-ac3-bitrate:
482 ``V4L2_CID_MPEG_AUDIO_AC3_BITRATE``
485 enum v4l2_mpeg_audio_ac3_bitrate -
486 AC-3 bitrate. Possible values are:
494 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
496 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
498 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
500 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
502 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
504 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
506 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
508 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
510 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
512 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
514 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
516 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
518 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
520 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
522 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
524 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
526 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
528 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
530 * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
535 .. _v4l2-mpeg-audio-mode:
537 ``V4L2_CID_MPEG_AUDIO_MODE``
540 enum v4l2_mpeg_audio_mode -
541 MPEG Audio mode. Possible values are:
549 * - ``V4L2_MPEG_AUDIO_MODE_STEREO``
551 * - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
553 * - ``V4L2_MPEG_AUDIO_MODE_DUAL``
555 * - ``V4L2_MPEG_AUDIO_MODE_MONO``
560 .. _v4l2-mpeg-audio-mode-extension:
562 ``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION``
565 enum v4l2_mpeg_audio_mode_extension -
566 Joint Stereo audio mode extension. In Layer I and II they indicate
567 which subbands are in intensity stereo. All other subbands are coded
568 in stereo. Layer III is not (yet) supported. Possible values are:
576 * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4``
577 - Subbands 4-31 in intensity stereo
578 * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8``
579 - Subbands 8-31 in intensity stereo
580 * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12``
581 - Subbands 12-31 in intensity stereo
582 * - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16``
583 - Subbands 16-31 in intensity stereo
587 .. _v4l2-mpeg-audio-emphasis:
589 ``V4L2_CID_MPEG_AUDIO_EMPHASIS``
592 enum v4l2_mpeg_audio_emphasis -
593 Audio Emphasis. Possible values are:
601 * - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
603 * - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
604 - 50/15 microsecond emphasis
605 * - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
610 .. _v4l2-mpeg-audio-crc:
612 ``V4L2_CID_MPEG_AUDIO_CRC``
615 enum v4l2_mpeg_audio_crc -
616 CRC method. Possible values are:
624 * - ``V4L2_MPEG_AUDIO_CRC_NONE``
626 * - ``V4L2_MPEG_AUDIO_CRC_CRC16``
627 - 16 bit parity check
631 ``V4L2_CID_MPEG_AUDIO_MUTE (boolean)``
632 Mutes the audio when capturing. This is not done by muting audio
633 hardware, which can still produce a slight hiss, but in the encoder
634 itself, guaranteeing a fixed and reproducible audio bitstream. 0 =
637 .. _v4l2-mpeg-audio-dec-playback:
639 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK``
642 enum v4l2_mpeg_audio_dec_playback -
643 Determines how monolingual audio should be played back. Possible
648 .. tabularcolumns:: |p{9.0cm}|p{8.5cm}|
654 * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
655 - Automatically determines the best playback mode.
656 * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
658 * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT``
659 - Left channel playback.
660 * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT``
661 - Right channel playback.
662 * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO``
664 * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
665 - Stereo playback with swapped left and right channels.
669 .. _v4l2-mpeg-audio-dec-multilingual-playback:
671 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK``
674 enum v4l2_mpeg_audio_dec_playback -
675 Determines how multilingual audio should be played back.
677 .. _v4l2-mpeg-video-encoding:
679 ``V4L2_CID_MPEG_VIDEO_ENCODING``
682 enum v4l2_mpeg_video_encoding -
683 MPEG Video encoding method. This control is specific to multiplexed
684 MPEG streams. Possible values are:
692 * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1``
693 - MPEG-1 Video encoding
694 * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2``
695 - MPEG-2 Video encoding
696 * - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC``
697 - MPEG-4 AVC (H.264) Video encoding
701 .. _v4l2-mpeg-video-aspect:
703 ``V4L2_CID_MPEG_VIDEO_ASPECT``
706 enum v4l2_mpeg_video_aspect -
707 Video aspect. Possible values are:
715 * - ``V4L2_MPEG_VIDEO_ASPECT_1x1``
716 * - ``V4L2_MPEG_VIDEO_ASPECT_4x3``
717 * - ``V4L2_MPEG_VIDEO_ASPECT_16x9``
718 * - ``V4L2_MPEG_VIDEO_ASPECT_221x100``
722 ``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
723 Number of B-Frames (default 2)
725 ``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
726 GOP size (default 12)
728 ``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
729 GOP closure (default 1)
731 ``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
732 Enable 3:2 pulldown (default 0)
734 .. _v4l2-mpeg-video-bitrate-mode:
736 ``V4L2_CID_MPEG_VIDEO_BITRATE_MODE``
739 enum v4l2_mpeg_video_bitrate_mode -
740 Video bitrate mode. Possible values are:
748 * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
750 * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
755 ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
756 Video bitrate in bits per second.
758 ``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)``
759 Peak video bitrate in bits per second. Must be larger or equal to
760 the average video bitrate. It is ignored if the video bitrate mode
761 is set to constant bitrate.
763 ``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)``
764 For every captured frame, skip this many subsequent frames (default
767 ``V4L2_CID_MPEG_VIDEO_MUTE (boolean)``
768 "Mutes" the video to a fixed color when capturing. This is useful
769 for testing, to produce a fixed video bitstream. 0 = unmuted, 1 =
772 ``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)``
773 Sets the "mute" color of the video. The supplied 32-bit integer is
774 interpreted as follows (bit 0 = least significant bit):
783 - V chrominance information
785 - U chrominance information
787 - Y luminance information
793 .. _v4l2-mpeg-video-dec-pts:
795 ``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)``
796 This read-only control returns the 33-bit video Presentation Time
797 Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the
798 currently displayed frame. This is the same PTS as is used in
799 :ref:`VIDIOC_DECODER_CMD`.
801 .. _v4l2-mpeg-video-dec-frame:
803 ``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)``
804 This read-only control returns the frame counter of the frame that
805 is currently displayed (decoded). This value is reset to 0 whenever
806 the decoder is started.
808 ``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)``
809 If enabled the decoder expects to receive a single slice per buffer,
810 otherwise the decoder expects a single frame in per buffer.
811 Applicable to the decoder, all codecs.
813 ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)``
814 Enable writing sample aspect ratio in the Video Usability
815 Information. Applicable to the H264 encoder.
817 .. _v4l2-mpeg-video-h264-vui-sar-idc:
819 ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC``
822 enum v4l2_mpeg_video_h264_vui_sar_idc -
823 VUI sample aspect ratio indicator for H.264 encoding. The value is
824 defined in the table E-1 in the standard. Applicable to the H264
833 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
835 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
837 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
839 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
841 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
843 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
845 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
847 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
849 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
851 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
853 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
855 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
857 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
859 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
861 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
863 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
865 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
867 * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
872 ``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)``
873 Extended sample aspect ratio width for H.264 VUI encoding.
874 Applicable to the H264 encoder.
876 ``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)``
877 Extended sample aspect ratio height for H.264 VUI encoding.
878 Applicable to the H264 encoder.
880 .. _v4l2-mpeg-video-h264-level:
882 ``V4L2_CID_MPEG_VIDEO_H264_LEVEL``
885 enum v4l2_mpeg_video_h264_level -
886 The level information for the H264 video elementary stream.
887 Applicable to the H264 encoder. Possible values are:
895 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
897 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
899 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
901 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
903 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
905 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
907 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
909 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
911 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
913 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
915 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
917 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
919 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
921 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
923 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
925 * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
930 .. _v4l2-mpeg-video-mpeg4-level:
932 ``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL``
935 enum v4l2_mpeg_video_mpeg4_level -
936 The level information for the MPEG4 elementary stream. Applicable to
937 the MPEG4 encoder. Possible values are:
945 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0``
947 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0B``
949 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_1``
951 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_2``
953 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3``
955 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3B``
957 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_4``
959 * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_5``
964 .. _v4l2-mpeg-video-h264-profile:
966 ``V4L2_CID_MPEG_VIDEO_H264_PROFILE``
969 enum v4l2_mpeg_video_h264_profile -
970 The profile information for H264. Applicable to the H264 encoder.
979 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
981 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
982 - Constrained Baseline profile
983 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
985 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
987 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
989 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
991 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
993 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE``
994 - High 444 Predictive profile
995 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA``
996 - High 10 Intra profile
997 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA``
998 - High 422 Intra profile
999 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA``
1000 - High 444 Intra profile
1001 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA``
1002 - CAVLC 444 Intra profile
1003 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE``
1004 - Scalable Baseline profile
1005 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH``
1006 - Scalable High profile
1007 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA``
1008 - Scalable High Intra profile
1009 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH``
1010 - Stereo High profile
1011 * - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH``
1012 - Multiview High profile
1016 .. _v4l2-mpeg-video-mpeg4-profile:
1018 ``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE``
1021 enum v4l2_mpeg_video_mpeg4_profile -
1022 The profile information for MPEG4. Applicable to the MPEG4 encoder.
1023 Possible values are:
1031 * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE``
1033 * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_SIMPLE``
1034 - Advanced Simple profile
1035 * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_CORE``
1037 * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE``
1038 - Simple Scalable profile
1039 * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY``
1044 ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
1045 The maximum number of reference pictures used for encoding.
1046 Applicable to the encoder.
1048 .. _v4l2-mpeg-video-multi-slice-mode:
1050 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE``
1053 enum v4l2_mpeg_video_multi_slice_mode -
1054 Determines how the encoder should handle division of frame into
1055 slices. Applicable to the encoder. Possible values are:
1059 .. tabularcolumns:: |p{8.7cm}|p{8.8cm}|
1065 * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE``
1066 - Single slice per frame.
1067 * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``
1068 - Multiple slices with set maximum number of macroblocks per slice.
1069 * - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``
1070 - Multiple slice with set maximum size in bytes per slice.
1074 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)``
1075 The maximum number of macroblocks in a slice. Used when
1076 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
1077 ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the
1080 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)``
1081 The maximum size of a slice in bytes. Used when
1082 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
1083 ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the
1086 .. _v4l2-mpeg-video-h264-loop-filter-mode:
1088 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE``
1091 enum v4l2_mpeg_video_h264_loop_filter_mode -
1092 Loop filter mode for H264 encoder. Possible values are:
1096 .. tabularcolumns:: |p{14.0cm}|p{3.5cm}|
1102 * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED``
1103 - Loop filter is enabled.
1104 * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED``
1105 - Loop filter is disabled.
1106 * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
1107 - Loop filter is disabled at the slice boundary.
1111 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)``
1112 Loop filter alpha coefficient, defined in the H264 standard.
1113 Applicable to the H264 encoder.
1115 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)``
1116 Loop filter beta coefficient, defined in the H264 standard.
1117 Applicable to the H264 encoder.
1119 .. _v4l2-mpeg-video-h264-entropy-mode:
1121 ``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE``
1124 enum v4l2_mpeg_video_h264_entropy_mode -
1125 Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264
1126 encoder. Possible values are:
1134 * - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC``
1135 - Use CAVLC entropy coding.
1136 * - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC``
1137 - Use CABAC entropy coding.
1141 ``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
1142 Enable 8X8 transform for H264. Applicable to the H264 encoder.
1144 ``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)``
1145 Cyclic intra macroblock refresh. This is the number of continuous
1146 macroblocks refreshed every frame. Each frame a successive set of
1147 macroblocks is refreshed until the cycle completes and starts from
1148 the top of the frame. Applicable to H264, H263 and MPEG4 encoder.
1150 ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)``
1151 Frame level rate control enable. If this control is disabled then
1152 the quantization parameter for each frame type is constant and set
1153 with appropriate controls (e.g.
1154 ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is
1155 enabled then quantization parameter is adjusted to meet the chosen
1156 bitrate. Minimum and maximum value for the quantization parameter
1157 can be set with appropriate controls (e.g.
1158 ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders.
1160 ``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
1161 Macroblock level rate control enable. Applicable to the MPEG4 and
1164 ``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
1165 Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
1168 ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
1169 Quantization parameter for an I frame for H263. Valid range: from 1
1172 ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
1173 Minimum quantization parameter for H263. Valid range: from 1 to 31.
1175 ``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
1176 Maximum quantization parameter for H263. Valid range: from 1 to 31.
1178 ``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
1179 Quantization parameter for an P frame for H263. Valid range: from 1
1182 ``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
1183 Quantization parameter for an B frame for H263. Valid range: from 1
1186 ``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
1187 Quantization parameter for an I frame for H264. Valid range: from 0
1190 ``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
1191 Minimum quantization parameter for H264. Valid range: from 0 to 51.
1193 ``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
1194 Maximum quantization parameter for H264. Valid range: from 0 to 51.
1196 ``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
1197 Quantization parameter for an P frame for H264. Valid range: from 0
1200 ``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
1201 Quantization parameter for an B frame for H264. Valid range: from 0
1204 ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
1205 Quantization parameter for an I frame for MPEG4. Valid range: from 1
1208 ``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
1209 Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
1211 ``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
1212 Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
1214 ``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
1215 Quantization parameter for an P frame for MPEG4. Valid range: from 1
1218 ``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
1219 Quantization parameter for an B frame for MPEG4. Valid range: from 1
1222 ``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)``
1223 The Video Buffer Verifier size in kilobytes, it is used as a
1224 limitation of frame skip. The VBV is defined in the standard as a
1225 mean to verify that the produced stream will be successfully
1226 decoded. The standard describes it as "Part of a hypothetical
1227 decoder that is conceptually connected to the output of the encoder.
1228 Its purpose is to provide a constraint on the variability of the
1229 data rate that an encoder or editing process may produce.".
1230 Applicable to the MPEG1, MPEG2, MPEG4 encoders.
1232 .. _v4l2-mpeg-video-vbv-delay:
1234 ``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
1235 Sets the initial delay in milliseconds for VBV buffer control.
1237 .. _v4l2-mpeg-video-hor-search-range:
1239 ``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)``
1240 Horizontal search range defines maximum horizontal search area in
1241 pixels to search and match for the present Macroblock (MB) in the
1242 reference picture. This V4L2 control macro is used to set horizontal
1243 search range for motion estimation module in video encoder.
1245 .. _v4l2-mpeg-video-vert-search-range:
1247 ``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)``
1248 Vertical search range defines maximum vertical search area in pixels
1249 to search and match for the present Macroblock (MB) in the reference
1250 picture. This V4L2 control macro is used to set vertical search
1251 range for motion estimation module in video encoder.
1253 .. _v4l2-mpeg-video-force-key-frame:
1255 ``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)``
1256 Force a key frame for the next queued buffer. Applicable to
1257 encoders. This is a general, codec-agnostic keyframe control.
1259 ``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)``
1260 The Coded Picture Buffer size in kilobytes, it is used as a
1261 limitation of frame skip. The CPB is defined in the H264 standard as
1262 a mean to verify that the produced stream will be successfully
1263 decoded. Applicable to the H264 encoder.
1265 ``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)``
1266 Period between I-frames in the open GOP for H264. In case of an open
1267 GOP this is the period between two I-frames. The period between IDR
1268 (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE
1269 control. An IDR frame, which stands for Instantaneous Decoding
1270 Refresh is an I-frame after which no prior frames are referenced.
1271 This means that a stream can be restarted from an IDR frame without
1272 the need to store or decode any previous frames. Applicable to the
1275 .. _v4l2-mpeg-video-header-mode:
1277 ``V4L2_CID_MPEG_VIDEO_HEADER_MODE``
1280 enum v4l2_mpeg_video_header_mode -
1281 Determines whether the header is returned as the first buffer or is
1282 it returned together with the first frame. Applicable to encoders.
1283 Possible values are:
1287 .. tabularcolumns:: |p{10.3cm}|p{7.2cm}|
1293 * - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE``
1294 - The stream header is returned separately in the first buffer.
1295 * - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME``
1296 - The stream header is returned together with the first encoded
1301 ``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)``
1302 Repeat the video sequence headers. Repeating these headers makes
1303 random access to the video stream easier. Applicable to the MPEG1, 2
1306 ``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)``
1307 Enabled the deblocking post processing filter for MPEG4 decoder.
1308 Applicable to the MPEG4 decoder.
1310 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
1311 vop_time_increment_resolution value for MPEG4. Applicable to the
1314 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
1315 vop_time_increment value for MPEG4. Applicable to the MPEG4
1318 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)``
1319 Enable generation of frame packing supplemental enhancement
1320 information in the encoded bitstream. The frame packing SEI message
1321 contains the arrangement of L and R planes for 3D viewing.
1322 Applicable to the H264 encoder.
1324 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)``
1325 Sets current frame as frame0 in frame packing SEI. Applicable to the
1328 .. _v4l2-mpeg-video-h264-sei-fp-arrangement-type:
1330 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE``
1333 enum v4l2_mpeg_video_h264_sei_fp_arrangement_type -
1334 Frame packing arrangement type for H264 SEI. Applicable to the H264
1335 encoder. Possible values are:
1337 .. tabularcolumns:: |p{12cm}|p{5.5cm}|
1343 * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD``
1344 - Pixels are alternatively from L and R.
1345 * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN``
1346 - L and R are interlaced by column.
1347 * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW``
1348 - L and R are interlaced by row.
1349 * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE``
1350 - L is on the left, R on the right.
1351 * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM``
1352 - L is on top, R on bottom.
1353 * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL``
1354 - One view per frame.
1358 ``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)``
1359 Enables flexible macroblock ordering in the encoded bitstream. It is
1360 a technique used for restructuring the ordering of macroblocks in
1361 pictures. Applicable to the H264 encoder.
1363 .. _v4l2-mpeg-video-h264-fmo-map-type:
1365 ``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE``
1368 enum v4l2_mpeg_video_h264_fmo_map_type -
1369 When using FMO, the map type divides the image in different scan
1370 patterns of macroblocks. Applicable to the H264 encoder. Possible
1373 .. tabularcolumns:: |p{12.5cm}|p{5.0cm}|
1379 * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
1380 - Slices are interleaved one after other with macroblocks in run
1382 * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES``
1383 - Scatters the macroblocks based on a mathematical function known to
1384 both encoder and decoder.
1385 * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER``
1386 - Macroblocks arranged in rectangular areas or regions of interest.
1387 * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT``
1388 - Slice groups grow in a cyclic way from centre to outwards.
1389 * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN``
1390 - Slice groups grow in raster scan pattern from left to right.
1391 * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN``
1392 - Slice groups grow in wipe scan pattern from top to bottom.
1393 * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT``
1394 - User defined map type.
1398 ``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
1399 Number of slice groups in FMO. Applicable to the H264 encoder.
1401 .. _v4l2-mpeg-video-h264-fmo-change-direction:
1403 ``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION``
1406 enum v4l2_mpeg_video_h264_fmo_change_dir -
1407 Specifies a direction of the slice group change for raster and wipe
1408 maps. Applicable to the H264 encoder. Possible values are:
1416 * - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT``
1417 - Raster scan or wipe right.
1418 * - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT``
1419 - Reverse raster scan or wipe left.
1423 ``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)``
1424 Specifies the size of the first slice group for raster and wipe map.
1425 Applicable to the H264 encoder.
1427 ``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)``
1428 Specifies the number of consecutive macroblocks for the interleaved
1429 map. Applicable to the H264 encoder.
1431 ``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
1432 Enables arbitrary slice ordering in encoded bitstream. Applicable to
1435 ``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)``
1436 Specifies the slice order in ASO. Applicable to the H264 encoder.
1437 The supplied 32-bit integer is interpreted as follows (bit 0 = least
1449 - Slice position or order
1453 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
1454 Enables H264 hierarchical coding. Applicable to the H264 encoder.
1456 .. _v4l2-mpeg-video-h264-hierarchical-coding-type:
1458 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE``
1461 enum v4l2_mpeg_video_h264_hierarchical_coding_type -
1462 Specifies the hierarchical coding type. Applicable to the H264
1463 encoder. Possible values are:
1471 * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
1472 - Hierarchical B coding.
1473 * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
1474 - Hierarchical P coding.
1478 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
1479 Specifies the number of hierarchical coding layers. Applicable to
1482 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)``
1483 Specifies a user defined QP for each layer. Applicable to the H264
1484 encoder. The supplied 32-bit integer is interpreted as follows (bit
1485 0 = least significant bit):
1501 MFC 5.1 MPEG Controls
1502 ---------------------
1504 The following MPEG class controls deal with MPEG decoding and encoding
1505 settings that are specific to the Multi Format Codec 5.1 device present
1506 in the S5P family of SoCs by Samsung.
1509 .. _mfc51-control-id:
1514 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)``
1515 If the display delay is enabled then the decoder is forced to return
1516 a CAPTURE buffer (decoded frame) after processing a certain number
1517 of OUTPUT buffers. The delay can be set through
1518 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This
1519 feature can be used for example for generating thumbnails of videos.
1520 Applicable to the H264 decoder.
1522 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)``
1523 Display delay value for H264 decoder. The decoder is forced to
1524 return a decoded frame after the set 'display delay' number of
1525 frames. If this number is low it may result in frames returned out
1526 of dispaly order, in addition the hardware may still be using the
1527 returned buffer as a reference picture for subsequent frames.
1529 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)``
1530 The number of reference pictures used for encoding a P picture.
1531 Applicable to the H264 encoder.
1533 ``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)``
1534 Padding enable in the encoder - use a color instead of repeating
1535 border pixels. Applicable to encoders.
1537 ``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)``
1538 Padding color in the encoder. Applicable to encoders. The supplied
1539 32-bit integer is interpreted as follows (bit 0 = least significant
1549 - V chrominance information
1551 - U chrominance information
1553 - Y luminance information
1559 ``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
1560 Reaction coefficient for MFC rate control. Applicable to encoders.
1564 #. Valid only when the frame level RC is enabled.
1566 #. For tight CBR, this field must be small (ex. 2 ~ 10). For
1567 VBR, this field must be large (ex. 100 ~ 1000).
1569 #. It is not recommended to use the greater number than
1570 FRAME_RATE * (10^9 / BIT_RATE).
1572 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
1573 Adaptive rate control for dark region. Valid only when H.264 and
1574 macroblock level RC is enabled
1575 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
1578 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)``
1579 Adaptive rate control for smooth region. Valid only when H.264 and
1580 macroblock level RC is enabled
1581 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
1584 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)``
1585 Adaptive rate control for static region. Valid only when H.264 and
1586 macroblock level RC is enabled
1587 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
1590 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)``
1591 Adaptive rate control for activity region. Valid only when H.264 and
1592 macroblock level RC is enabled
1593 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
1596 .. _v4l2-mpeg-mfc51-video-frame-skip-mode:
1598 ``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE``
1601 enum v4l2_mpeg_mfc51_video_frame_skip_mode -
1602 Indicates in what conditions the encoder should skip frames. If
1603 encoding a frame would cause the encoded stream to be larger then a
1604 chosen data limit then the frame will be skipped. Possible values
1608 .. tabularcolumns:: |p{9.0cm}|p{8.5cm}|
1614 * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED``
1615 - Frame skip mode is disabled.
1616 * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT``
1617 - Frame skip mode enabled and buffer limit is set by the chosen
1618 level and is defined by the standard.
1619 * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT``
1620 - Frame skip mode enabled and buffer limit is set by the VBV
1621 (MPEG1/2/4) or CPB (H264) buffer size control.
1625 ``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)``
1626 Enable rate-control with fixed target bit. If this setting is
1627 enabled, then the rate control logic of the encoder will calculate
1628 the average bitrate for a GOP and keep it below or equal the set
1629 bitrate target. Otherwise the rate control logic calculates the
1630 overall average bitrate for the stream and keeps it below or equal
1631 to the set bitrate. In the first case the average bitrate for the
1632 whole stream will be smaller then the set bitrate. This is caused
1633 because the average is calculated for smaller number of frames, on
1634 the other hand enabling this setting will ensure that the stream
1635 will meet tight bandwidth constraints. Applicable to encoders.
1637 .. _v4l2-mpeg-mfc51-video-force-frame-type:
1639 ``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE``
1642 enum v4l2_mpeg_mfc51_video_force_frame_type -
1643 Force a frame type for the next queued buffer. Applicable to
1644 encoders. Possible values are:
1652 * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
1653 - Forcing a specific frame type disabled.
1654 * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
1656 * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
1657 - Force a non-coded frame.
1662 CX2341x MPEG Controls
1663 ---------------------
1665 The following MPEG class controls deal with MPEG encoding settings that
1666 are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
1669 .. _cx2341x-control-id:
1674 .. _v4l2-mpeg-cx2341x-video-spatial-filter-mode:
1676 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE``
1679 enum v4l2_mpeg_cx2341x_video_spatial_filter_mode -
1680 Sets the Spatial Filter mode (default ``MANUAL``). Possible values
1689 * - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL``
1690 - Choose the filter manually
1691 * - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO``
1692 - Choose the filter automatically
1696 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
1697 The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
1700 .. _luma-spatial-filter-type:
1702 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE``
1705 enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type -
1706 Select the algorithm to use for the Luma Spatial Filter (default
1707 ``1D_HOR``). Possible values:
1711 .. tabularcolumns:: |p{14.5cm}|p{3.0cm}|
1717 * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
1719 * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR``
1720 - One-dimensional horizontal
1721 * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT``
1722 - One-dimensional vertical
1723 * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE``
1724 - Two-dimensional separable
1725 * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE``
1726 - Two-dimensional symmetrical non-separable
1730 .. _chroma-spatial-filter-type:
1732 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE``
1735 enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type -
1736 Select the algorithm for the Chroma Spatial Filter (default
1737 ``1D_HOR``). Possible values are:
1745 * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
1747 * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
1748 - One-dimensional horizontal
1752 .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode:
1754 ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE``
1757 enum v4l2_mpeg_cx2341x_video_temporal_filter_mode -
1758 Sets the Temporal Filter mode (default ``MANUAL``). Possible values
1767 * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL``
1768 - Choose the filter manually
1769 * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO``
1770 - Choose the filter automatically
1774 ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))``
1775 The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default
1776 is 8 for full-scale capturing and 0 for scaled capturing.)
1778 .. _v4l2-mpeg-cx2341x-video-median-filter-type:
1780 ``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE``
1783 enum v4l2_mpeg_cx2341x_video_median_filter_type -
1784 Median Filter Type (default ``OFF``). Possible values are:
1792 * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
1794 * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
1796 * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
1798 * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
1799 - Horizontal and vertical filter
1800 * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
1805 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
1806 Threshold above which the luminance median filter is enabled
1809 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
1810 Threshold below which the luminance median filter is enabled
1813 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
1814 Threshold above which the chroma median filter is enabled (default
1817 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
1818 Threshold below which the chroma median filter is enabled (default
1821 ``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)``
1822 The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into
1823 the stream between every four video frames. The packet size is 2048
1824 bytes, including the packet_start_code_prefix and stream_id
1825 fields. The stream_id is 0xBF (private stream 2). The payload
1826 consists of 0x00 bytes, to be filled in by the application. 0 = do
1827 not insert, 1 = insert packets.
1830 VPX Control Reference
1831 ---------------------
1833 The VPX controls include controls for encoding parameters of VPx video
1842 .. _v4l2-vpx-num-partitions:
1844 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS``
1847 enum v4l2_vp8_num_partitions -
1848 The number of token partitions to use in VP8 encoder. Possible
1857 * - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION``
1858 - 1 coefficient partition
1859 * - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS``
1860 - 2 coefficient partitions
1861 * - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS``
1862 - 4 coefficient partitions
1863 * - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS``
1864 - 8 coefficient partitions
1868 ``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
1869 Setting this prevents intra 4x4 mode in the intra mode decision.
1871 .. _v4l2-vpx-num-ref-frames:
1873 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES``
1876 enum v4l2_vp8_num_ref_frames -
1877 The number of reference pictures for encoding P frames. Possible
1880 .. tabularcolumns:: |p{7.9cm}|p{9.6cm}|
1886 * - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME``
1887 - Last encoded frame will be searched
1888 * - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME``
1889 - Two frames will be searched among the last encoded frame, the
1890 golden frame and the alternate reference (altref) frame. The
1891 encoder implementation will decide which two are chosen.
1892 * - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME``
1893 - The last encoded frame, the golden frame and the altref frame will
1898 ``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)``
1899 Indicates the loop filter level. The adjustment of the loop filter
1900 level is done via a delta value against a baseline loop filter
1903 ``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)``
1904 This parameter affects the loop filter. Anything above zero weakens
1905 the deblocking effect on the loop filter.
1907 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)``
1908 Sets the refresh period for the golden frame. The period is defined
1909 in number of frames. For a value of 'n', every nth frame starting
1910 from the first key frame will be taken as a golden frame. For eg.
1911 for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden
1912 frame refresh period is set as 4, the frames 0, 4, 8 etc will be
1913 taken as the golden frames as frame 0 is always a key frame.
1915 .. _v4l2-vpx-golden-frame-sel:
1917 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL``
1920 enum v4l2_vp8_golden_frame_sel -
1921 Selects the golden frame for encoding. Possible values are:
1927 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
1933 * - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV``
1934 - Use the (n-2)th frame as a golden frame, current frame index being
1936 * - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD``
1937 - Use the previous specific frame indicated by
1938 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD`` as a
1946 ``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
1947 Minimum quantization parameter for VP8.
1949 ``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
1950 Maximum quantization parameter for VP8.
1952 ``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
1953 Quantization parameter for an I frame for VP8.
1955 ``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
1956 Quantization parameter for a P frame for VP8.
1958 .. _v4l2-mpeg-video-vp8-profile:
1960 ``V4L2_CID_MPEG_VIDEO_VP8_PROFILE``
1963 enum v4l2_mpeg_video_vp8_profile -
1964 This control allows selecting the profile for VP8 encoder.
1965 This is also used to enumerate supported profiles by VP8 encoder or decoder.
1966 Possible values are:
1972 * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_0``
1974 * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_1``
1976 * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_2``
1978 * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_3``
1981 .. _v4l2-mpeg-video-vp9-profile:
1983 ``V4L2_CID_MPEG_VIDEO_VP9_PROFILE``
1986 enum v4l2_mpeg_video_vp9_profile -
1987 This control allows selecting the profile for VP9 encoder.
1988 This is also used to enumerate supported profiles by VP9 encoder or decoder.
1989 Possible values are:
1995 * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_0``
1997 * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_1``
1999 * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_2``
2001 * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_3``
2005 High Efficiency Video Coding (HEVC/H.265) Control Reference
2006 -----------------------------------------------------------
2008 The HEVC/H.265 controls include controls for encoding parameters of HEVC/H.265
2012 .. _hevc-control-id:
2014 HEVC/H.265 Control IDs
2015 ^^^^^^^^^^^^^^^^^^^^^^
2017 ``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)``
2018 Minimum quantization parameter for HEVC.
2019 Valid range: from 0 to 51.
2021 ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)``
2022 Maximum quantization parameter for HEVC.
2023 Valid range: from 0 to 51.
2025 ``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP (integer)``
2026 Quantization parameter for an I frame for HEVC.
2027 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2028 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2030 ``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_QP (integer)``
2031 Quantization parameter for a P frame for HEVC.
2032 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2033 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2035 ``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_QP (integer)``
2036 Quantization parameter for a B frame for HEVC.
2037 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2038 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2040 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_QP (boolean)``
2041 HIERARCHICAL_QP allows the host to specify the quantization parameter
2042 values for each temporal layer through HIERARCHICAL_QP_LAYER. This is
2043 valid only if HIERARCHICAL_CODING_LAYER is greater than 1. Setting the
2044 control value to 1 enables setting of the QP values for the layers.
2046 .. _v4l2-hevc-hier-coding-type:
2048 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_TYPE``
2051 enum v4l2_mpeg_video_hevc_hier_coding_type -
2052 Selects the hierarchical coding type for encoding. Possible values are:
2058 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2064 * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_B``
2065 - Use the B frame for hierarchical coding.
2066 * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_P``
2067 - Use the P frame for hierarchical coding.
2074 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_LAYER (integer)``
2075 Selects the hierarchical coding layer. In normal encoding
2076 (non-hierarchial coding), it should be zero. Possible values are [0, 6].
2077 0 indicates HIERARCHICAL CODING LAYER 0, 1 indicates HIERARCHICAL CODING
2080 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_QP (integer)``
2081 Indicates quantization parameter for hierarchical coding layer 0.
2082 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2083 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2085 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_QP (integer)``
2086 Indicates quantization parameter for hierarchical coding layer 1.
2087 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2088 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2090 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_QP (integer)``
2091 Indicates quantization parameter for hierarchical coding layer 2.
2092 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2093 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2095 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_QP (integer)``
2096 Indicates quantization parameter for hierarchical coding layer 3.
2097 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2098 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2100 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_QP (integer)``
2101 Indicates quantization parameter for hierarchical coding layer 4.
2102 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2103 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2105 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_QP (integer)``
2106 Indicates quantization parameter for hierarchical coding layer 5.
2107 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2108 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2110 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_QP (integer)``
2111 Indicates quantization parameter for hierarchical coding layer 6.
2112 Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP,
2113 V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP].
2115 .. _v4l2-hevc-profile:
2117 ``V4L2_CID_MPEG_VIDEO_HEVC_PROFILE``
2120 enum v4l2_mpeg_video_hevc_profile -
2121 Select the desired profile for HEVC encoder.
2127 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2133 * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN``
2135 * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_STILL_PICTURE``
2136 - Main still picture profile.
2137 * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_10``
2145 .. _v4l2-hevc-level:
2147 ``V4L2_CID_MPEG_VIDEO_HEVC_LEVEL``
2150 enum v4l2_mpeg_video_hevc_level -
2151 Selects the desired level for HEVC encoder.
2157 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2163 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1``
2165 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2``
2167 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1``
2169 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3``
2171 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1``
2173 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4``
2175 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1``
2177 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5``
2179 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1``
2181 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2``
2183 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6``
2185 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1``
2187 * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2``
2195 ``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)``
2196 Indicates the number of evenly spaced subintervals, called ticks, within
2197 one second. This is a 16 bit unsigned integer and has a maximum value up to
2198 0xffff and a minimum value of 1.
2202 ``V4L2_CID_MPEG_VIDEO_HEVC_TIER``
2205 enum v4l2_mpeg_video_hevc_tier -
2206 TIER_FLAG specifies tiers information of the HEVC encoded picture. Tier
2207 were made to deal with applications that differ in terms of maximum bit
2208 rate. Setting the flag to 0 selects HEVC tier as Main tier and setting
2209 this flag to 1 indicates High tier. High tier is for applications requiring
2216 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2222 * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN``
2224 * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH``
2232 ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)``
2233 Selects HEVC maximum coding unit depth.
2235 .. _v4l2-hevc-loop-filter-mode:
2237 ``V4L2_CID_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE``
2240 enum v4l2_mpeg_video_hevc_loop_filter_mode -
2241 Loop filter mode for HEVC encoder. Possible values are:
2247 .. tabularcolumns:: |p{10.7cm}|p{6.3cm}|
2253 * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED``
2254 - Loop filter is disabled.
2255 * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_ENABLED``
2256 - Loop filter is enabled.
2257 * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
2258 - Loop filter is disabled at the slice boundary.
2265 ``V4L2_CID_MPEG_VIDEO_HEVC_LF_BETA_OFFSET_DIV2 (integer)``
2266 Selects HEVC loop filter beta offset. The valid range is [-6, +6].
2268 ``V4L2_CID_MPEG_VIDEO_HEVC_LF_TC_OFFSET_DIV2 (integer)``
2269 Selects HEVC loop filter tc offset. The valid range is [-6, +6].
2271 .. _v4l2-hevc-refresh-type:
2273 ``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_TYPE``
2276 enum v4l2_mpeg_video_hevc_hier_refresh_type -
2277 Selects refresh type for HEVC encoder.
2278 Host has to specify the period into
2279 V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD.
2285 .. tabularcolumns:: |p{8.0cm}|p{9.0cm}|
2291 * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_NONE``
2292 - Use the B frame for hierarchical coding.
2293 * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_CRA``
2294 - Use CRA (Clean Random Access Unit) picture encoding.
2295 * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_IDR``
2296 - Use IDR (Instantaneous Decoding Refresh) picture encoding.
2303 ``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD (integer)``
2304 Selects the refresh period for HEVC encoder.
2305 This specifies the number of I pictures between two CRA/IDR pictures.
2306 This is valid only if REFRESH_TYPE is not 0.
2308 ``V4L2_CID_MPEG_VIDEO_HEVC_LOSSLESS_CU (boolean)``
2309 Indicates HEVC lossless encoding. Setting it to 0 disables lossless
2310 encoding. Setting it to 1 enables lossless encoding.
2312 ``V4L2_CID_MPEG_VIDEO_HEVC_CONST_INTRA_PRED (boolean)``
2313 Indicates constant intra prediction for HEVC encoder. Specifies the
2314 constrained intra prediction in which intra largest coding unit (LCU)
2315 prediction is performed by using residual data and decoded samples of
2316 neighboring intra LCU only. Setting the value to 1 enables constant intra
2317 prediction and setting the value to 0 disables constant intra prediction.
2319 ``V4L2_CID_MPEG_VIDEO_HEVC_WAVEFRONT (boolean)``
2320 Indicates wavefront parallel processing for HEVC encoder. Setting it to 0
2321 disables the feature and setting it to 1 enables the wavefront parallel
2324 ``V4L2_CID_MPEG_VIDEO_HEVC_GENERAL_PB (boolean)``
2325 Setting the value to 1 enables combination of P and B frame for HEVC
2328 ``V4L2_CID_MPEG_VIDEO_HEVC_TEMPORAL_ID (boolean)``
2329 Indicates temporal identifier for HEVC encoder which is enabled by
2330 setting the value to 1.
2332 ``V4L2_CID_MPEG_VIDEO_HEVC_STRONG_SMOOTHING (boolean)``
2333 Indicates bi-linear interpolation is conditionally used in the intra
2334 prediction filtering process in the CVS when set to 1. Indicates bi-linear
2335 interpolation is not used in the CVS when set to 0.
2337 ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_NUM_MERGE_MV_MINUS1 (integer)``
2338 Indicates maximum number of merge candidate motion vectors.
2339 Values are from 0 to 4.
2341 ``V4L2_CID_MPEG_VIDEO_HEVC_TMV_PREDICTION (boolean)``
2342 Indicates temporal motion vector prediction for HEVC encoder. Setting it to
2343 1 enables the prediction. Setting it to 0 disables the prediction.
2345 ``V4L2_CID_MPEG_VIDEO_HEVC_WITHOUT_STARTCODE (boolean)``
2346 Specifies if HEVC generates a stream with a size of the length field
2347 instead of start code pattern. The size of the length field is configurable
2348 through the V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD control. Setting
2349 the value to 0 disables encoding without startcode pattern. Setting the
2350 value to 1 will enables encoding without startcode pattern.
2352 .. _v4l2-hevc-size-of-length-field:
2354 ``V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD``
2357 enum v4l2_mpeg_video_hevc_size_of_length_field -
2358 Indicates the size of length field.
2359 This is valid when encoding WITHOUT_STARTCODE_ENABLE is enabled.
2365 .. tabularcolumns:: |p{6.0cm}|p{11.0cm}|
2371 * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_0``
2372 - Generate start code pattern (Normal).
2373 * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_1``
2374 - Generate size of length field instead of start code pattern and length is 1.
2375 * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_2``
2376 - Generate size of length field instead of start code pattern and length is 2.
2377 * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_4``
2378 - Generate size of length field instead of start code pattern and length is 4.
2384 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_BR (integer)``
2385 Indicates bit rate for hierarchical coding layer 0 for HEVC encoder.
2387 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_BR (integer)``
2388 Indicates bit rate for hierarchical coding layer 1 for HEVC encoder.
2390 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_BR (integer)``
2391 Indicates bit rate for hierarchical coding layer 2 for HEVC encoder.
2393 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_BR (integer)``
2394 Indicates bit rate for hierarchical coding layer 3 for HEVC encoder.
2396 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_BR (integer)``
2397 Indicates bit rate for hierarchical coding layer 4 for HEVC encoder.
2399 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_BR (integer)``
2400 Indicates bit rate for hierarchical coding layer 5 for HEVC encoder.
2402 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_BR (integer)``
2403 Indicates bit rate for hierarchical coding layer 6 for HEVC encoder.
2405 ``V4L2_CID_MPEG_VIDEO_REF_NUMBER_FOR_PFRAMES (integer)``
2406 Selects number of P reference pictures required for HEVC encoder.
2407 P-Frame can use 1 or 2 frames for reference.
2409 ``V4L2_CID_MPEG_VIDEO_PREPEND_SPSPPS_TO_IDR (integer)``
2410 Indicates whether to generate SPS and PPS at every IDR. Setting it to 0
2411 disables generating SPS and PPS at every IDR. Setting it to one enables
2412 generating SPS and PPS at every IDR.
2415 .. _camera-controls:
2417 Camera Control Reference
2418 ========================
2420 The Camera class includes controls for mechanical (or equivalent
2421 digital) features of a device such as controllable lenses or sensors.
2424 .. _camera-control-id:
2429 ``V4L2_CID_CAMERA_CLASS (class)``
2430 The Camera class descriptor. Calling
2431 :ref:`VIDIOC_QUERYCTRL` for this control will
2432 return a description of this control class.
2434 .. _v4l2-exposure-auto-type:
2436 ``V4L2_CID_EXPOSURE_AUTO``
2439 enum v4l2_exposure_auto_type -
2440 Enables automatic adjustments of the exposure time and/or iris
2441 aperture. The effect of manual changes of the exposure time or iris
2442 aperture while these features are enabled is undefined, drivers
2443 should ignore such requests. Possible values are:
2451 * - ``V4L2_EXPOSURE_AUTO``
2452 - Automatic exposure time, automatic iris aperture.
2453 * - ``V4L2_EXPOSURE_MANUAL``
2454 - Manual exposure time, manual iris.
2455 * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
2456 - Manual exposure time, auto iris.
2457 * - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
2458 - Auto exposure time, manual iris.
2462 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
2463 Determines the exposure time of the camera sensor. The exposure time
2464 is limited by the frame interval. Drivers should interpret the
2465 values as 100 µs units, where the value 1 stands for 1/10000th of a
2466 second, 10000 for 1 second and 100000 for 10 seconds.
2468 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
2469 When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
2470 ``APERTURE_PRIORITY``, this control determines if the device may
2471 dynamically vary the frame rate. By default this feature is disabled
2472 (0) and the frame rate must remain constant.
2474 ``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)``
2475 Determines the automatic exposure compensation, it is effective only
2476 when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
2477 ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
2478 terms of EV, drivers should interpret the values as 0.001 EV units,
2479 where the value 1000 stands for +1 EV.
2481 Increasing the exposure compensation value is equivalent to
2482 decreasing the exposure value (EV) and will increase the amount of
2483 light at the image sensor. The camera performs the exposure
2484 compensation by adjusting absolute exposure time and/or aperture.
2486 .. _v4l2-exposure-metering:
2488 ``V4L2_CID_EXPOSURE_METERING``
2491 enum v4l2_exposure_metering -
2492 Determines how the camera measures the amount of light available for
2493 the frame exposure. Possible values are:
2495 .. tabularcolumns:: |p{8.5cm}|p{9.0cm}|
2501 * - ``V4L2_EXPOSURE_METERING_AVERAGE``
2502 - Use the light information coming from the entire frame and average
2503 giving no weighting to any particular portion of the metered area.
2504 * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
2505 - Average the light information coming from the entire frame giving
2506 priority to the center of the metered area.
2507 * - ``V4L2_EXPOSURE_METERING_SPOT``
2508 - Measure only very small area at the center of the frame.
2509 * - ``V4L2_EXPOSURE_METERING_MATRIX``
2510 - A multi-zone metering. The light intensity is measured in several
2511 points of the frame and the results are combined. The algorithm of
2512 the zones selection and their significance in calculating the
2513 final value is device dependent.
2517 ``V4L2_CID_PAN_RELATIVE (integer)``
2518 This control turns the camera horizontally by the specified amount.
2519 The unit is undefined. A positive value moves the camera to the
2520 right (clockwise when viewed from above), a negative value to the
2521 left. A value of zero does not cause motion. This is a write-only
2524 ``V4L2_CID_TILT_RELATIVE (integer)``
2525 This control turns the camera vertically by the specified amount.
2526 The unit is undefined. A positive value moves the camera up, a
2527 negative value down. A value of zero does not cause motion. This is
2528 a write-only control.
2530 ``V4L2_CID_PAN_RESET (button)``
2531 When this control is set, the camera moves horizontally to the
2534 ``V4L2_CID_TILT_RESET (button)``
2535 When this control is set, the camera moves vertically to the default
2538 ``V4L2_CID_PAN_ABSOLUTE (integer)``
2539 This control turns the camera horizontally to the specified
2540 position. Positive values move the camera to the right (clockwise
2541 when viewed from above), negative values to the left. Drivers should
2542 interpret the values as arc seconds, with valid values between -180
2543 * 3600 and +180 * 3600 inclusive.
2545 ``V4L2_CID_TILT_ABSOLUTE (integer)``
2546 This control turns the camera vertically to the specified position.
2547 Positive values move the camera up, negative values down. Drivers
2548 should interpret the values as arc seconds, with valid values
2549 between -180 * 3600 and +180 * 3600 inclusive.
2551 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
2552 This control sets the focal point of the camera to the specified
2553 position. The unit is undefined. Positive values set the focus
2554 closer to the camera, negative values towards infinity.
2556 ``V4L2_CID_FOCUS_RELATIVE (integer)``
2557 This control moves the focal point of the camera by the specified
2558 amount. The unit is undefined. Positive values move the focus closer
2559 to the camera, negative values towards infinity. This is a
2562 ``V4L2_CID_FOCUS_AUTO (boolean)``
2563 Enables continuous automatic focus adjustments. The effect of manual
2564 focus adjustments while this feature is enabled is undefined,
2565 drivers should ignore such requests.
2567 ``V4L2_CID_AUTO_FOCUS_START (button)``
2568 Starts single auto focus process. The effect of setting this control
2569 when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
2570 drivers should ignore such requests.
2572 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
2573 Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
2574 control. It is effective only when the continuous autofocus is
2575 disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
2578 .. _v4l2-auto-focus-status:
2580 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
2581 The automatic focus status. This is a read-only control.
2583 Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
2584 control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
2587 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
2593 * - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
2594 - Automatic focus is not active.
2595 * - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
2596 - Automatic focusing is in progress.
2597 * - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
2598 - Focus has been reached.
2599 * - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
2600 - Automatic focus has failed, the driver will not transition from
2601 this state until another action is performed by an application.
2605 .. _v4l2-auto-focus-range:
2607 ``V4L2_CID_AUTO_FOCUS_RANGE``
2610 enum v4l2_auto_focus_range -
2611 Determines auto focus distance range for which lens may be adjusted.
2613 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
2619 * - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
2620 - The camera automatically selects the focus range.
2621 * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
2622 - Normal distance range, limited for best automatic focus
2624 * - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
2625 - Macro (close-up) auto focus. The camera will use its minimum
2626 possible distance for auto focus.
2627 * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
2628 - The lens is set to focus on an object at infinite distance.
2632 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
2633 Specify the objective lens focal length as an absolute value. The
2634 zoom unit is driver-specific and its value should be a positive
2637 ``V4L2_CID_ZOOM_RELATIVE (integer)``
2638 Specify the objective lens focal length relatively to the current
2639 value. Positive values move the zoom lens group towards the
2640 telephoto direction, negative values towards the wide-angle
2641 direction. The zoom unit is driver-specific. This is a write-only
2644 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
2645 Move the objective lens group at the specified speed until it
2646 reaches physical device limits or until an explicit request to stop
2647 the movement. A positive value moves the zoom lens group towards the
2648 telephoto direction. A value of zero stops the zoom lens group
2649 movement. A negative value moves the zoom lens group towards the
2650 wide-angle direction. The zoom speed unit is driver-specific.
2652 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
2653 This control sets the camera's aperture to the specified value. The
2654 unit is undefined. Larger values open the iris wider, smaller values
2657 ``V4L2_CID_IRIS_RELATIVE (integer)``
2658 This control modifies the camera's aperture by the specified amount.
2659 The unit is undefined. Positive values open the iris one step
2660 further, negative values close it one step further. This is a
2663 ``V4L2_CID_PRIVACY (boolean)``
2664 Prevent video from being acquired by the camera. When this control
2665 is set to ``TRUE`` (1), no image can be captured by the camera.
2666 Common means to enforce privacy are mechanical obturation of the
2667 sensor and firmware image processing, but the device is not
2668 restricted to these methods. Devices that implement the privacy
2669 control must support read access and may support write access.
2671 ``V4L2_CID_BAND_STOP_FILTER (integer)``
2672 Switch the band-stop filter of a camera sensor on or off, or specify
2673 its strength. Such band-stop filters can be used, for example, to
2674 filter out the fluorescent light component.
2676 .. _v4l2-auto-n-preset-white-balance:
2678 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
2681 enum v4l2_auto_n_preset_white_balance -
2682 Sets white balance to automatic, manual or a preset. The presets
2683 determine color temperature of the light as a hint to the camera for
2684 white balance adjustments resulting in most accurate color
2685 representation. The following white balance presets are listed in
2686 order of increasing color temperature.
2688 .. tabularcolumns:: |p{7.0 cm}|p{10.5cm}|
2694 * - ``V4L2_WHITE_BALANCE_MANUAL``
2695 - Manual white balance.
2696 * - ``V4L2_WHITE_BALANCE_AUTO``
2697 - Automatic white balance adjustments.
2698 * - ``V4L2_WHITE_BALANCE_INCANDESCENT``
2699 - White balance setting for incandescent (tungsten) lighting. It
2700 generally cools down the colors and corresponds approximately to
2701 2500...3500 K color temperature range.
2702 * - ``V4L2_WHITE_BALANCE_FLUORESCENT``
2703 - White balance preset for fluorescent lighting. It corresponds
2704 approximately to 4000...5000 K color temperature.
2705 * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
2706 - With this setting the camera will compensate for fluorescent H
2708 * - ``V4L2_WHITE_BALANCE_HORIZON``
2709 - White balance setting for horizon daylight. It corresponds
2710 approximately to 5000 K color temperature.
2711 * - ``V4L2_WHITE_BALANCE_DAYLIGHT``
2712 - White balance preset for daylight (with clear sky). It corresponds
2713 approximately to 5000...6500 K color temperature.
2714 * - ``V4L2_WHITE_BALANCE_FLASH``
2715 - With this setting the camera will compensate for the flash light.
2716 It slightly warms up the colors and corresponds roughly to
2717 5000...5500 K color temperature.
2718 * - ``V4L2_WHITE_BALANCE_CLOUDY``
2719 - White balance preset for moderately overcast sky. This option
2720 corresponds approximately to 6500...8000 K color temperature
2722 * - ``V4L2_WHITE_BALANCE_SHADE``
2723 - White balance preset for shade or heavily overcast sky. It
2724 corresponds approximately to 9000...10000 K color temperature.
2728 .. _v4l2-wide-dynamic-range:
2730 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
2731 Enables or disables the camera's wide dynamic range feature. This
2732 feature allows to obtain clear images in situations where intensity
2733 of the illumination varies significantly throughout the scene, i.e.
2734 there are simultaneously very dark and very bright areas. It is most
2735 commonly realized in cameras by combining two subsequent frames with
2736 different exposure times. [#f1]_
2738 .. _v4l2-image-stabilization:
2740 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
2741 Enables or disables image stabilization.
2743 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
2744 Determines ISO equivalent of an image sensor indicating the sensor's
2745 sensitivity to light. The numbers are expressed in arithmetic scale,
2746 as per :ref:`iso12232` standard, where doubling the sensor
2747 sensitivity is represented by doubling the numerical ISO value.
2748 Applications should interpret the values as standard ISO values
2749 multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
2750 Drivers will usually support only a subset of standard ISO values.
2751 The effect of setting this control while the
2752 ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
2753 than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
2754 should ignore such requests.
2756 .. _v4l2-iso-sensitivity-auto-type:
2758 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
2761 enum v4l2_iso_sensitivity_type -
2762 Enables or disables automatic ISO sensitivity adjustments.
2770 * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
2771 - Manual ISO sensitivity.
2772 * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
2773 - Automatic ISO sensitivity adjustments.
2777 .. _v4l2-scene-mode:
2779 ``V4L2_CID_SCENE_MODE``
2782 enum v4l2_scene_mode -
2783 This control allows to select scene programs as the camera automatic
2784 modes optimized for common shooting scenes. Within these modes the
2785 camera determines best exposure, aperture, focusing, light metering,
2786 white balance and equivalent sensitivity. The controls of those
2787 parameters are influenced by the scene mode control. An exact
2788 behavior in each mode is subject to the camera specification.
2790 When the scene mode feature is not used, this control should be set
2791 to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
2792 controls are accessible. The following scene programs are defined:
2794 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
2800 * - ``V4L2_SCENE_MODE_NONE``
2801 - The scene mode feature is disabled.
2802 * - ``V4L2_SCENE_MODE_BACKLIGHT``
2803 - Backlight. Compensates for dark shadows when light is coming from
2804 behind a subject, also by automatically turning on the flash.
2805 * - ``V4L2_SCENE_MODE_BEACH_SNOW``
2806 - Beach and snow. This mode compensates for all-white or bright
2807 scenes, which tend to look gray and low contrast, when camera's
2808 automatic exposure is based on an average scene brightness. To
2809 compensate, this mode automatically slightly overexposes the
2810 frames. The white balance may also be adjusted to compensate for
2811 the fact that reflected snow looks bluish rather than white.
2812 * - ``V4L2_SCENE_MODE_CANDLELIGHT``
2813 - Candle light. The camera generally raises the ISO sensitivity and
2814 lowers the shutter speed. This mode compensates for relatively
2815 close subject in the scene. The flash is disabled in order to
2816 preserve the ambiance of the light.
2817 * - ``V4L2_SCENE_MODE_DAWN_DUSK``
2818 - Dawn and dusk. Preserves the colors seen in low natural light
2819 before dusk and after down. The camera may turn off the flash, and
2820 automatically focus at infinity. It will usually boost saturation
2821 and lower the shutter speed.
2822 * - ``V4L2_SCENE_MODE_FALL_COLORS``
2823 - Fall colors. Increases saturation and adjusts white balance for
2824 color enhancement. Pictures of autumn leaves get saturated reds
2826 * - ``V4L2_SCENE_MODE_FIREWORKS``
2827 - Fireworks. Long exposure times are used to capture the expanding
2828 burst of light from a firework. The camera may invoke image
2830 * - ``V4L2_SCENE_MODE_LANDSCAPE``
2831 - Landscape. The camera may choose a small aperture to provide deep
2832 depth of field and long exposure duration to help capture detail
2833 in dim light conditions. The focus is fixed at infinity. Suitable
2834 for distant and wide scenery.
2835 * - ``V4L2_SCENE_MODE_NIGHT``
2836 - Night, also known as Night Landscape. Designed for low light
2837 conditions, it preserves detail in the dark areas without blowing
2838 out bright objects. The camera generally sets itself to a
2839 medium-to-high ISO sensitivity, with a relatively long exposure
2840 time, and turns flash off. As such, there will be increased image
2841 noise and the possibility of blurred image.
2842 * - ``V4L2_SCENE_MODE_PARTY_INDOOR``
2843 - Party and indoor. Designed to capture indoor scenes that are lit
2844 by indoor background lighting as well as the flash. The camera
2845 usually increases ISO sensitivity, and adjusts exposure for the
2846 low light conditions.
2847 * - ``V4L2_SCENE_MODE_PORTRAIT``
2848 - Portrait. The camera adjusts the aperture so that the depth of
2849 field is reduced, which helps to isolate the subject against a
2850 smooth background. Most cameras recognize the presence of faces in
2851 the scene and focus on them. The color hue is adjusted to enhance
2852 skin tones. The intensity of the flash is often reduced.
2853 * - ``V4L2_SCENE_MODE_SPORTS``
2854 - Sports. Significantly increases ISO and uses a fast shutter speed
2855 to freeze motion of rapidly-moving subjects. Increased image noise
2856 may be seen in this mode.
2857 * - ``V4L2_SCENE_MODE_SUNSET``
2858 - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
2860 * - ``V4L2_SCENE_MODE_TEXT``
2861 - Text. It applies extra contrast and sharpness, it is typically a
2862 black-and-white mode optimized for readability. Automatic focus
2863 may be switched to close-up mode and this setting may also involve
2864 some lens-distortion correction.
2868 ``V4L2_CID_3A_LOCK (bitmask)``
2869 This control locks or unlocks the automatic focus, exposure and
2870 white balance. The automatic adjustments can be paused independently
2871 by setting the corresponding lock bit to 1. The camera then retains
2872 the settings until the lock bit is cleared. The following lock bits
2875 When a given algorithm is not enabled, drivers should ignore
2876 requests to lock it and should return no error. An example might be
2877 an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
2878 ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
2879 value of this control may be changed by exposure, white balance or
2888 * - ``V4L2_LOCK_EXPOSURE``
2889 - Automatic exposure adjustments lock.
2890 * - ``V4L2_LOCK_WHITE_BALANCE``
2891 - Automatic white balance adjustments lock.
2892 * - ``V4L2_LOCK_FOCUS``
2893 - Automatic focus lock.
2897 ``V4L2_CID_PAN_SPEED (integer)``
2898 This control turns the camera horizontally at the specific speed.
2899 The unit is undefined. A positive value moves the camera to the
2900 right (clockwise when viewed from above), a negative value to the
2901 left. A value of zero stops the motion if one is in progress and has
2902 no effect otherwise.
2904 ``V4L2_CID_TILT_SPEED (integer)``
2905 This control turns the camera vertically at the specified speed. The
2906 unit is undefined. A positive value moves the camera up, a negative
2907 value down. A value of zero stops the motion if one is in progress
2908 and has no effect otherwise.
2913 FM Transmitter Control Reference
2914 ================================
2916 The FM Transmitter (FM_TX) class includes controls for common features
2917 of FM transmissions capable devices. Currently this class includes
2918 parameters for audio compression, pilot tone generation, audio deviation
2919 limiter, RDS transmission and tuning power features.
2922 .. _fm-tx-control-id:
2927 ``V4L2_CID_FM_TX_CLASS (class)``
2928 The FM_TX class descriptor. Calling
2929 :ref:`VIDIOC_QUERYCTRL` for this control will
2930 return a description of this control class.
2932 ``V4L2_CID_RDS_TX_DEVIATION (integer)``
2933 Configures RDS signal frequency deviation level in Hz. The range and
2934 step are driver-specific.
2936 ``V4L2_CID_RDS_TX_PI (integer)``
2937 Sets the RDS Programme Identification field for transmission.
2939 ``V4L2_CID_RDS_TX_PTY (integer)``
2940 Sets the RDS Programme Type field for transmission. This encodes up
2941 to 31 pre-defined programme types.
2943 ``V4L2_CID_RDS_TX_PS_NAME (string)``
2944 Sets the Programme Service name (PS_NAME) for transmission. It is
2945 intended for static display on a receiver. It is the primary aid to
2946 listeners in programme service identification and selection. In
2947 Annex E of :ref:`iec62106`, the RDS specification, there is a full
2948 description of the correct character encoding for Programme Service
2949 name strings. Also from RDS specification, PS is usually a single
2950 eight character text. However, it is also possible to find receivers
2951 which can scroll strings sized as 8 x N characters. So, this control
2952 must be configured with steps of 8 characters. The result is it must
2953 always contain a string with size multiple of 8.
2955 ``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
2956 Sets the Radio Text info for transmission. It is a textual
2957 description of what is being broadcasted. RDS Radio Text can be
2958 applied when broadcaster wishes to transmit longer PS names,
2959 programme-related information or any other text. In these cases,
2960 RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
2961 The encoding for Radio Text strings is also fully described in Annex
2962 E of :ref:`iec62106`. The length of Radio Text strings depends on
2963 which RDS Block is being used to transmit it, either 32 (2A block)
2964 or 64 (2B block). However, it is also possible to find receivers
2965 which can scroll strings sized as 32 x N or 64 x N characters. So,
2966 this control must be configured with steps of 32 or 64 characters.
2967 The result is it must always contain a string with size multiple of
2970 ``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
2971 Sets the Mono/Stereo bit of the Decoder Identification code. If set,
2972 then the audio was recorded as stereo.
2974 ``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
2976 `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
2977 bit of the Decoder Identification code. If set, then the audio was
2978 recorded using an artificial head.
2980 ``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
2981 Sets the Compressed bit of the Decoder Identification code. If set,
2982 then the audio is compressed.
2984 ``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
2985 Sets the Dynamic PTY bit of the Decoder Identification code. If set,
2986 then the PTY code is dynamically switched.
2988 ``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
2989 If set, then a traffic announcement is in progress.
2991 ``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
2992 If set, then the tuned programme carries traffic announcements.
2994 ``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
2995 If set, then this channel broadcasts music. If cleared, then it
2996 broadcasts speech. If the transmitter doesn't make this distinction,
2997 then it should be set.
2999 ``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
3000 If set, then transmit alternate frequencies.
3002 ``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
3003 The alternate frequencies in kHz units. The RDS standard allows for
3004 up to 25 frequencies to be defined. Drivers may support fewer
3005 frequencies so check the array size.
3007 ``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
3008 Enables or disables the audio deviation limiter feature. The limiter
3009 is useful when trying to maximize the audio volume, minimize
3010 receiver-generated distortion and prevent overmodulation.
3012 ``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
3013 Sets the audio deviation limiter feature release time. Unit is in
3014 useconds. Step and range are driver-specific.
3016 ``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
3017 Configures audio frequency deviation level in Hz. The range and step
3018 are driver-specific.
3020 ``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
3021 Enables or disables the audio compression feature. This feature
3022 amplifies signals below the threshold by a fixed gain and compresses
3023 audio signals above the threshold by the ratio of Threshold/(Gain +
3026 ``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
3027 Sets the gain for audio compression feature. It is a dB value. The
3028 range and step are driver-specific.
3030 ``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
3031 Sets the threshold level for audio compression freature. It is a dB
3032 value. The range and step are driver-specific.
3034 ``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
3035 Sets the attack time for audio compression feature. It is a useconds
3036 value. The range and step are driver-specific.
3038 ``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
3039 Sets the release time for audio compression feature. It is a
3040 useconds value. The range and step are driver-specific.
3042 ``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
3043 Enables or disables the pilot tone generation feature.
3045 ``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
3046 Configures pilot tone frequency deviation level. Unit is in Hz. The
3047 range and step are driver-specific.
3049 ``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
3050 Configures pilot tone frequency value. Unit is in Hz. The range and
3051 step are driver-specific.
3053 ``V4L2_CID_TUNE_PREEMPHASIS``
3056 enum v4l2_preemphasis -
3057 Configures the pre-emphasis value for broadcasting. A pre-emphasis
3058 filter is applied to the broadcast to accentuate the high audio
3059 frequencies. Depending on the region, a time constant of either 50
3060 or 75 useconds is used. The enum v4l2_preemphasis defines possible
3061 values for pre-emphasis. Here they are:
3069 * - ``V4L2_PREEMPHASIS_DISABLED``
3070 - No pre-emphasis is applied.
3071 * - ``V4L2_PREEMPHASIS_50_uS``
3072 - A pre-emphasis of 50 uS is used.
3073 * - ``V4L2_PREEMPHASIS_75_uS``
3074 - A pre-emphasis of 75 uS is used.
3078 ``V4L2_CID_TUNE_POWER_LEVEL (integer)``
3079 Sets the output power level for signal transmission. Unit is in
3080 dBuV. Range and step are driver-specific.
3082 ``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
3083 This selects the value of antenna tuning capacitor manually or
3084 automatically if set to zero. Unit, range and step are
3087 For more details about RDS specification, refer to :ref:`iec62106`
3088 document, from CENELEC.
3093 Flash Control Reference
3094 =======================
3096 The V4L2 flash controls are intended to provide generic access to flash
3097 controller devices. Flash controller devices are typically used in
3100 The interface can support both LED and xenon flash devices. As of
3101 writing this, there is no xenon flash driver using this interface.
3104 .. _flash-controls-use-cases:
3110 Unsynchronised LED flash (software strobe)
3111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3113 Unsynchronised LED flash is controlled directly by the host as the
3114 sensor. The flash must be enabled by the host before the exposure of the
3115 image starts and disabled once it ends. The host is fully responsible
3116 for the timing of the flash.
3118 Example of such device: Nokia N900.
3121 Synchronised LED flash (hardware strobe)
3122 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3124 The synchronised LED flash is pre-programmed by the host (power and
3125 timeout) but controlled by the sensor through a strobe signal from the
3126 sensor to the flash.
3128 The sensor controls the flash duration and timing. This information
3129 typically must be made available to the sensor.
3135 LED flash may be used as torch in conjunction with another use case
3136 involving camera or individually.
3139 .. _flash-control-id:
3144 ``V4L2_CID_FLASH_CLASS (class)``
3145 The FLASH class descriptor.
3147 ``V4L2_CID_FLASH_LED_MODE (menu)``
3148 Defines the mode of the flash LED, the high-power white LED attached
3149 to the flash controller. Setting this control may not be possible in
3150 presence of some faults. See V4L2_CID_FLASH_FAULT.
3158 * - ``V4L2_FLASH_LED_MODE_NONE``
3160 * - ``V4L2_FLASH_LED_MODE_FLASH``
3162 * - ``V4L2_FLASH_LED_MODE_TORCH``
3163 - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
3167 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
3168 Defines the source of the flash LED strobe.
3170 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3176 * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
3177 - The flash strobe is triggered by using the
3178 V4L2_CID_FLASH_STROBE control.
3179 * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
3180 - The flash strobe is triggered by an external source. Typically
3181 this is a sensor, which makes it possible to synchronises the
3182 flash strobe start to exposure start.
3186 ``V4L2_CID_FLASH_STROBE (button)``
3187 Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
3188 V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
3189 is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
3190 control may not be possible in presence of some faults. See
3191 V4L2_CID_FLASH_FAULT.
3193 ``V4L2_CID_FLASH_STROBE_STOP (button)``
3194 Stop flash strobe immediately.
3196 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
3197 Strobe status: whether the flash is strobing at the moment or not.
3198 This is a read-only control.
3200 ``V4L2_CID_FLASH_TIMEOUT (integer)``
3201 Hardware timeout for flash. The flash strobe is stopped after this
3202 period of time has passed from the start of the strobe.
3204 ``V4L2_CID_FLASH_INTENSITY (integer)``
3205 Intensity of the flash strobe when the flash LED is in flash mode
3206 (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
3209 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
3210 Intensity of the flash LED in torch mode
3211 (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
3212 if possible. Setting this control may not be possible in presence of
3213 some faults. See V4L2_CID_FLASH_FAULT.
3215 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
3216 Intensity of the indicator LED. The indicator LED may be fully
3217 independent of the flash LED. The unit should be microamps (uA) if
3220 ``V4L2_CID_FLASH_FAULT (bitmask)``
3221 Faults related to the flash. The faults tell about specific problems
3222 in the flash chip itself or the LEDs attached to it. Faults may
3223 prevent further use of some of the flash controls. In particular,
3224 V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
3225 if the fault affects the flash LED. Exactly which faults have such
3226 an effect is chip dependent. Reading the faults resets the control
3227 and returns the chip to a usable state if possible.
3229 .. tabularcolumns:: |p{8.0cm}|p{9.5cm}|
3235 * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
3236 - Flash controller voltage to the flash LED has exceeded the limit
3237 specific to the flash controller.
3238 * - ``V4L2_FLASH_FAULT_TIMEOUT``
3239 - The flash strobe was still on when the timeout set by the user ---
3240 V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
3241 controllers may set this in all such conditions.
3242 * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
3243 - The flash controller has overheated.
3244 * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
3245 - The short circuit protection of the flash controller has been
3247 * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
3248 - Current in the LED power supply has exceeded the limit specific to
3249 the flash controller.
3250 * - ``V4L2_FLASH_FAULT_INDICATOR``
3251 - The flash controller has detected a short or open circuit
3252 condition on the indicator LED.
3253 * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
3254 - Flash controller voltage to the flash LED has been below the
3255 minimum limit specific to the flash controller.
3256 * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
3257 - The input voltage of the flash controller is below the limit under
3258 which strobing the flash at full current will not be possible.The
3259 condition persists until this flag is no longer set.
3260 * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
3261 - The temperature of the LED has exceeded its allowed upper limit.
3265 ``V4L2_CID_FLASH_CHARGE (boolean)``
3266 Enable or disable charging of the xenon flash capacitor.
3268 ``V4L2_CID_FLASH_READY (boolean)``
3269 Is the flash ready to strobe? Xenon flashes require their capacitors
3270 charged before strobing. LED flashes often require a cooldown period
3271 after strobe during which another strobe will not be possible. This
3272 is a read-only control.
3277 JPEG Control Reference
3278 ======================
3280 The JPEG class includes controls for common features of JPEG encoders
3281 and decoders. Currently it includes features for codecs implementing
3282 progressive baseline DCT compression process with Huffman entrophy
3286 .. _jpeg-control-id:
3291 ``V4L2_CID_JPEG_CLASS (class)``
3292 The JPEG class descriptor. Calling
3293 :ref:`VIDIOC_QUERYCTRL` for this control will
3294 return a description of this control class.
3296 ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
3297 The chroma subsampling factors describe how each component of an
3298 input image is sampled, in respect to maximum sample rate in each
3299 spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
3300 details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
3301 how Cb and Cr components are downsampled after converting an input
3302 image from RGB to Y'CbCr color space.
3304 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3310 * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
3311 - No chroma subsampling, each pixel has Y, Cr and Cb values.
3312 * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
3313 - Horizontally subsample Cr, Cb components by a factor of 2.
3314 * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
3315 - Subsample Cr, Cb components horizontally and vertically by 2.
3316 * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
3317 - Horizontally subsample Cr, Cb components by a factor of 4.
3318 * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
3319 - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
3320 * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
3321 - Use only luminance component.
3325 ``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
3326 The restart interval determines an interval of inserting RSTm
3327 markers (m = 0..7). The purpose of these markers is to additionally
3328 reinitialize the encoder process, in order to process blocks of an
3329 image independently. For the lossy compression processes the restart
3330 interval unit is MCU (Minimum Coded Unit) and its value is contained
3331 in DRI (Define Restart Interval) marker. If
3332 ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
3333 markers will not be inserted.
3335 .. _jpeg-quality-control:
3337 ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
3338 ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
3339 between image quality and size. It provides simpler method for
3340 applications to control image quality, without a need for direct
3341 reconfiguration of luminance and chrominance quantization tables. In
3342 cases where a driver uses quantization tables configured directly by
3343 an application, using interfaces defined elsewhere,
3344 ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
3347 The value range of this control is driver-specific. Only positive,
3348 non-zero values are meaningful. The recommended range is 1 - 100,
3349 where larger values correspond to better image quality.
3351 .. _jpeg-active-marker-control:
3353 ``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
3354 Specify which JPEG markers are included in compressed stream. This
3355 control is valid only for encoders.
3363 * - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
3364 - Application data segment APP\ :sub:`0`.
3365 * - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
3366 - Application data segment APP\ :sub:`1`.
3367 * - ``V4L2_JPEG_ACTIVE_MARKER_COM``
3369 * - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
3370 - Quantization tables segment.
3371 * - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
3372 - Huffman tables segment.
3376 For more details about JPEG specification, refer to :ref:`itu-t81`,
3377 :ref:`jfif`, :ref:`w3c-jpeg-jfif`.
3380 .. _image-source-controls:
3382 Image Source Control Reference
3383 ==============================
3385 The Image Source control class is intended for low-level control of
3386 image source devices such as image sensors. The devices feature an
3387 analogue to digital converter and a bus transmitter to transmit the
3388 image data out of the device.
3391 .. _image-source-control-id:
3393 Image Source Control IDs
3394 ------------------------
3396 ``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
3397 The IMAGE_SOURCE class descriptor.
3399 ``V4L2_CID_VBLANK (integer)``
3400 Vertical blanking. The idle period after every frame during which no
3401 image data is produced. The unit of vertical blanking is a line.
3402 Every line has length of the image width plus horizontal blanking at
3403 the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
3406 ``V4L2_CID_HBLANK (integer)``
3407 Horizontal blanking. The idle period after every line of image data
3408 during which no image data is produced. The unit of horizontal
3411 ``V4L2_CID_ANALOGUE_GAIN (integer)``
3412 Analogue gain is gain affecting all colour components in the pixel
3413 matrix. The gain operation is performed in the analogue domain
3414 before A/D conversion.
3416 ``V4L2_CID_TEST_PATTERN_RED (integer)``
3417 Test pattern red colour component.
3419 ``V4L2_CID_TEST_PATTERN_GREENR (integer)``
3420 Test pattern green (next to red) colour component.
3422 ``V4L2_CID_TEST_PATTERN_BLUE (integer)``
3423 Test pattern blue colour component.
3425 ``V4L2_CID_TEST_PATTERN_GREENB (integer)``
3426 Test pattern green (next to blue) colour component.
3429 .. _image-process-controls:
3431 Image Process Control Reference
3432 ===============================
3434 The Image Process control class is intended for low-level control of
3435 image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
3436 controls in this class affect processing the image, and do not control
3440 .. _image-process-control-id:
3442 Image Process Control IDs
3443 -------------------------
3445 ``V4L2_CID_IMAGE_PROC_CLASS (class)``
3446 The IMAGE_PROC class descriptor.
3448 ``V4L2_CID_LINK_FREQ (integer menu)``
3449 Data bus frequency. Together with the media bus pixel code, bus type
3450 (clock cycles per sample), the data bus frequency defines the pixel
3451 rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly
3452 elsewhere, if the device is not an image sensor). The frame rate can
3453 be calculated from the pixel clock, image width and height and
3454 horizontal and vertical blanking. While the pixel rate control may
3455 be defined elsewhere than in the subdev containing the pixel array,
3456 the frame rate cannot be obtained from that information. This is
3457 because only on the pixel array it can be assumed that the vertical
3458 and horizontal blanking information is exact: no other blanking is
3459 allowed in the pixel array. The selection of frame rate is performed
3460 by selecting the desired horizontal and vertical blanking. The unit
3461 of this control is Hz.
3463 ``V4L2_CID_PIXEL_RATE (64-bit integer)``
3464 Pixel rate in the source pads of the subdev. This control is
3465 read-only and its unit is pixels / second.
3467 ``V4L2_CID_TEST_PATTERN (menu)``
3468 Some capture/display/sensor devices have the capability to generate
3469 test pattern images. These hardware specific test patterns can be
3470 used to test if a device is working properly.
3472 ``V4L2_CID_DEINTERLACING_MODE (menu)``
3473 The video deinterlacing mode (such as Bob, Weave, ...). The menu items are
3474 driver specific and are documented in :ref:`v4l-drivers`.
3476 ``V4L2_CID_DIGITAL_GAIN (integer)``
3477 Digital gain is the value by which all colour components
3478 are multiplied by. Typically the digital gain applied is the
3479 control value divided by e.g. 0x100, meaning that to get no
3480 digital gain the control value needs to be 0x100. The no-gain
3481 configuration is also typically the default.
3486 Digital Video Control Reference
3487 ===============================
3489 The Digital Video control class is intended to control receivers and
3490 transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
3491 `DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
3492 (Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
3493 (:ref:`dp`). These controls are generally expected to be private to
3494 the receiver or transmitter subdevice that implements them, so they are
3495 only exposed on the ``/dev/v4l-subdev*`` device node.
3499 Note that these devices can have multiple input or output pads which are
3500 hooked up to e.g. HDMI connectors. Even though the subdevice will
3501 receive or transmit video from/to only one of those pads, the other pads
3502 can still be active when it comes to EDID (Extended Display
3503 Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
3504 Content Protection System, :ref:`hdcp`) processing, allowing the
3505 device to do the fairly slow EDID/HDCP handling in advance. This allows
3506 for quick switching between connectors.
3508 These pads appear in several of the controls in this section as
3509 bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
3510 1, etc. The maximum value of the control is the set of valid pads.
3515 Digital Video Control IDs
3516 -------------------------
3518 ``V4L2_CID_DV_CLASS (class)``
3519 The Digital Video class descriptor.
3521 ``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
3522 Many connectors have a hotplug pin which is high if EDID information
3523 is available from the source. This control shows the state of the
3524 hotplug pin as seen by the transmitter. Each bit corresponds to an
3525 output pad on the transmitter. If an output pad does not have an
3526 associated hotplug pin, then the bit for that pad will be 0. This
3527 read-only control is applicable to DVI-D, HDMI and DisplayPort
3530 ``V4L2_CID_DV_TX_RXSENSE (bitmask)``
3531 Rx Sense is the detection of pull-ups on the TMDS clock lines. This
3532 normally means that the sink has left/entered standby (i.e. the
3533 transmitter can sense that the receiver is ready to receive video).
3534 Each bit corresponds to an output pad on the transmitter. If an
3535 output pad does not have an associated Rx Sense, then the bit for
3536 that pad will be 0. This read-only control is applicable to DVI-D
3539 ``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
3540 When the transmitter sees the hotplug signal from the receiver it
3541 will attempt to read the EDID. If set, then the transmitter has read
3542 at least the first block (= 128 bytes). Each bit corresponds to an
3543 output pad on the transmitter. If an output pad does not support
3544 EDIDs, then the bit for that pad will be 0. This read-only control
3545 is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
3547 ``V4L2_CID_DV_TX_MODE``
3550 enum v4l2_dv_tx_mode -
3551 HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
3552 mode (video + audio + auxiliary data). This control selects which
3553 mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
3554 This control is applicable to HDMI connectors.
3556 ``V4L2_CID_DV_TX_RGB_RANGE``
3559 enum v4l2_dv_rgb_range -
3560 Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
3561 follows the RGB quantization range specified in the standard for the
3562 video interface (ie. :ref:`cea861` for HDMI).
3563 V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
3564 standard to be compatible with sinks that have not implemented the
3565 standard correctly (unfortunately quite common for HDMI and DVI-D).
3566 Full range allows all possible values to be used whereas limited
3567 range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
3568 the number of bits per component. This control is applicable to VGA,
3569 DVI-A/D, HDMI and DisplayPort connectors.
3571 ``V4L2_CID_DV_TX_IT_CONTENT_TYPE``
3574 enum v4l2_dv_it_content_type -
3575 Configures the IT Content Type of the transmitted video. This
3576 information is sent over HDMI and DisplayPort connectors as part of
3577 the AVI InfoFrame. The term 'IT Content' is used for content that
3578 originates from a computer as opposed to content from a TV broadcast
3579 or an analog source. The enum v4l2_dv_it_content_type defines
3580 the possible content types:
3582 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3588 * - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
3589 - Graphics content. Pixel data should be passed unfiltered and
3590 without analog reconstruction.
3591 * - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
3592 - Photo content. The content is derived from digital still pictures.
3593 The content should be passed through with minimal scaling and
3594 picture enhancements.
3595 * - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
3597 * - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
3598 - Game content. Audio and video latency should be minimized.
3599 * - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
3600 - No IT Content information is available and the ITC bit in the AVI
3601 InfoFrame is set to 0.
3605 ``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
3606 Detects whether the receiver receives power from the source (e.g.
3607 HDMI carries 5V on one of the pins). This is often used to power an
3608 eeprom which contains EDID information, such that the source can
3609 read the EDID even if the sink is in standby/power off. Each bit
3610 corresponds to an input pad on the receiver. If an input pad
3611 cannot detect whether power is present, then the bit for that pad
3612 will be 0. This read-only control is applicable to DVI-D, HDMI and
3613 DisplayPort connectors.
3615 ``V4L2_CID_DV_RX_RGB_RANGE``
3618 enum v4l2_dv_rgb_range -
3619 Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
3620 follows the RGB quantization range specified in the standard for the
3621 video interface (ie. :ref:`cea861` for HDMI).
3622 V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
3623 standard to be compatible with sources that have not implemented the
3624 standard correctly (unfortunately quite common for HDMI and DVI-D).
3625 Full range allows all possible values to be used whereas limited
3626 range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
3627 the number of bits per component. This control is applicable to VGA,
3628 DVI-A/D, HDMI and DisplayPort connectors.
3630 ``V4L2_CID_DV_RX_IT_CONTENT_TYPE``
3633 enum v4l2_dv_it_content_type -
3634 Reads the IT Content Type of the received video. This information is
3635 sent over HDMI and DisplayPort connectors as part of the AVI
3636 InfoFrame. The term 'IT Content' is used for content that originates
3637 from a computer as opposed to content from a TV broadcast or an
3638 analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
3639 available content types.
3644 FM Receiver Control Reference
3645 =============================
3647 The FM Receiver (FM_RX) class includes controls for common features of
3648 FM Reception capable devices.
3651 .. _fm-rx-control-id:
3656 ``V4L2_CID_FM_RX_CLASS (class)``
3657 The FM_RX class descriptor. Calling
3658 :ref:`VIDIOC_QUERYCTRL` for this control will
3659 return a description of this control class.
3661 ``V4L2_CID_RDS_RECEPTION (boolean)``
3662 Enables/disables RDS reception by the radio tuner
3664 ``V4L2_CID_RDS_RX_PTY (integer)``
3665 Gets RDS Programme Type field. This encodes up to 31 pre-defined
3668 ``V4L2_CID_RDS_RX_PS_NAME (string)``
3669 Gets the Programme Service name (PS_NAME). It is intended for
3670 static display on a receiver. It is the primary aid to listeners in
3671 programme service identification and selection. In Annex E of
3672 :ref:`iec62106`, the RDS specification, there is a full
3673 description of the correct character encoding for Programme Service
3674 name strings. Also from RDS specification, PS is usually a single
3675 eight character text. However, it is also possible to find receivers
3676 which can scroll strings sized as 8 x N characters. So, this control
3677 must be configured with steps of 8 characters. The result is it must
3678 always contain a string with size multiple of 8.
3680 ``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
3681 Gets the Radio Text info. It is a textual description of what is
3682 being broadcasted. RDS Radio Text can be applied when broadcaster
3683 wishes to transmit longer PS names, programme-related information or
3684 any other text. In these cases, RadioText can be used in addition to
3685 ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
3686 also fully described in Annex E of :ref:`iec62106`. The length of
3687 Radio Text strings depends on which RDS Block is being used to
3688 transmit it, either 32 (2A block) or 64 (2B block). However, it is
3689 also possible to find receivers which can scroll strings sized as 32
3690 x N or 64 x N characters. So, this control must be configured with
3691 steps of 32 or 64 characters. The result is it must always contain a
3692 string with size multiple of 32 or 64.
3694 ``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
3695 If set, then a traffic announcement is in progress.
3697 ``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
3698 If set, then the tuned programme carries traffic announcements.
3700 ``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
3701 If set, then this channel broadcasts music. If cleared, then it
3702 broadcasts speech. If the transmitter doesn't make this distinction,
3703 then it will be set.
3705 ``V4L2_CID_TUNE_DEEMPHASIS``
3708 enum v4l2_deemphasis -
3709 Configures the de-emphasis value for reception. A de-emphasis filter
3710 is applied to the broadcast to accentuate the high audio
3711 frequencies. Depending on the region, a time constant of either 50
3712 or 75 useconds is used. The enum v4l2_deemphasis defines possible
3713 values for de-emphasis. Here they are:
3721 * - ``V4L2_DEEMPHASIS_DISABLED``
3722 - No de-emphasis is applied.
3723 * - ``V4L2_DEEMPHASIS_50_uS``
3724 - A de-emphasis of 50 uS is used.
3725 * - ``V4L2_DEEMPHASIS_75_uS``
3726 - A de-emphasis of 75 uS is used.
3731 .. _detect-controls:
3733 Detect Control Reference
3734 ========================
3736 The Detect class includes controls for common features of various motion
3737 or object detection capable devices.
3740 .. _detect-control-id:
3745 ``V4L2_CID_DETECT_CLASS (class)``
3746 The Detect class descriptor. Calling
3747 :ref:`VIDIOC_QUERYCTRL` for this control will
3748 return a description of this control class.
3750 ``V4L2_CID_DETECT_MD_MODE (menu)``
3751 Sets the motion detection mode.
3753 .. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
3759 * - ``V4L2_DETECT_MD_MODE_DISABLED``
3760 - Disable motion detection.
3761 * - ``V4L2_DETECT_MD_MODE_GLOBAL``
3762 - Use a single motion detection threshold.
3763 * - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
3764 - The image is divided into a grid, each cell with its own motion
3765 detection threshold. These thresholds are set through the
3766 ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
3767 * - ``V4L2_DETECT_MD_MODE_REGION_GRID``
3768 - The image is divided into a grid, each cell with its own region
3769 value that specifies which per-region motion detection thresholds
3770 should be used. Each region has its own thresholds. How these
3771 per-region thresholds are set up is driver-specific. The region
3772 values for the grid are set through the
3773 ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
3777 ``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
3778 Sets the global motion detection threshold to be used with the
3779 ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
3781 ``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
3782 Sets the motion detection thresholds for each cell in the grid. To
3783 be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
3784 detection mode. Matrix element (0, 0) represents the cell at the
3785 top-left of the grid.
3787 ``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
3788 Sets the motion detection region value for each cell in the grid. To
3789 be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
3790 detection mode. Matrix element (0, 0) represents the cell at the
3791 top-left of the grid.
3794 .. _rf-tuner-controls:
3796 RF Tuner Control Reference
3797 ==========================
3799 The RF Tuner (RF_TUNER) class includes controls for common features of
3800 devices having RF tuner.
3802 In this context, RF tuner is radio receiver circuit between antenna and
3803 demodulator. It receives radio frequency (RF) from the antenna and
3804 converts that received signal to lower intermediate frequency (IF) or
3805 baseband frequency (BB). Tuners that could do baseband output are often
3806 called Zero-IF tuners. Older tuners were typically simple PLL tuners
3807 inside a metal box, whilst newer ones are highly integrated chips
3808 without a metal box "silicon tuners". These controls are mostly
3809 applicable for new feature rich silicon tuners, just because older
3810 tuners does not have much adjustable features.
3812 For more information about RF tuners see
3813 `Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
3814 and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
3818 .. _rf-tuner-control-id:
3820 RF_TUNER Control IDs
3821 --------------------
3823 ``V4L2_CID_RF_TUNER_CLASS (class)``
3824 The RF_TUNER class descriptor. Calling
3825 :ref:`VIDIOC_QUERYCTRL` for this control will
3826 return a description of this control class.
3828 ``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
3829 Enables/disables tuner radio channel bandwidth configuration. In
3830 automatic mode bandwidth configuration is performed by the driver.
3832 ``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
3833 Filter(s) on tuner signal path are used to filter signal according
3834 to receiving party needs. Driver configures filters to fulfill
3835 desired bandwidth requirement. Used when
3836 V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
3837 range and step are driver-specific.
3839 ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
3840 Enables/disables LNA automatic gain control (AGC)
3842 ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
3843 Enables/disables mixer automatic gain control (AGC)
3845 ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
3846 Enables/disables IF automatic gain control (AGC)
3848 ``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
3849 The RF amplifier is the very first amplifier on the receiver signal
3850 path, just right after the antenna input. The difference between the
3851 LNA gain and the RF gain in this document is that the LNA gain is
3852 integrated in the tuner chip while the RF gain is a separate chip.
3853 There may be both RF and LNA gain controls in the same device. The
3854 range and step are driver-specific.
3856 ``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
3857 LNA (low noise amplifier) gain is first gain stage on the RF tuner
3858 signal path. It is located very close to tuner antenna input. Used
3859 when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
3860 ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
3861 differs from the each others. The range and step are
3864 ``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
3865 Mixer gain is second gain stage on the RF tuner signal path. It is
3866 located inside mixer block, where RF signal is down-converted by the
3867 mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
3868 The range and step are driver-specific.
3870 ``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
3871 IF gain is last gain stage on the RF tuner signal path. It is
3872 located on output of RF tuner. It controls signal level of
3873 intermediate frequency output or baseband output. Used when
3874 ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
3875 are driver-specific.
3877 ``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
3878 Is synthesizer PLL locked? RF tuner is receiving given frequency
3879 when that control is set. This is a read-only control.
3882 This control may be changed to a menu control in the future, if more
3883 options are required.