Documentation/media/uapi/v4l/extended-controls.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _extended-controls:
   4
   5 *****************
   6 Extended Controls
   7 *****************
   8
   9
  10 Introduction
  11 ============
  12
  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.
  17
  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
  25 that format.
  26
  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.
  30
  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.
  36
  37
  38 The Extended Control API
  39 ========================
  40
  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.
  50
  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.
  60
  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.
  63
  64 It is also possible to use an empty control array (``count`` == 0) to check
  65 whether the specified control class is supported.
  66
  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.
  72
  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.
  79
  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.
  86
  87 .. note::
  88
  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>`
  94       ioctls to check this.
  95
  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.
 101
 102 All controls use machine endianness.
 103
 104
 105 Enumerating Extended Controls
 106 =============================
 107
 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:
 111
 112
 113 .. code-block:: c
 114
 115     struct v4l2_queryctrl qctrl;
 116
 117     qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
 118     while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
 119         /* ... */
 120         qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
 121     }
 122
 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.
 127
 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:
 132
 133
 134 .. code-block:: c
 135
 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)
 139             break;
 140             /* ... */
 141         qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
 142     }
 143
 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.
 153
 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.
 160
 161
 162 Creating Control Panels
 163 =======================
 164
 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.
 172
 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
 176 details.
 177
 178
 179 .. _mpeg-controls:
 180
 181 Codec Control Reference
 182 =======================
 183
 184 Below all controls within the Codec control class are described. First
 185 the generic controls, then controls specific for certain hardware.
 186
 187 .. note::
 188
 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
 192    encoding formats.
 193
 194
 195 Generic Codec Controls
 196 ----------------------
 197
 198
 199 .. _mpeg-control-id:
 200
 201 Codec Control IDs
 202 ^^^^^^^^^^^^^^^^^
 203
 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.
 209
 210 .. _v4l2-mpeg-stream-type:
 211
 212 ``V4L2_CID_MPEG_STREAM_TYPE``
 213     (enum)
 214
 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:
 220
 221
 222
 223 .. flat-table::
 224     :header-rows:  0
 225     :stub-columns: 0
 226
 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
 239
 240
 241
 242 ``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
 243     Program Map Table Packet ID for the MPEG transport stream (default
 244     16)
 245
 246 ``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
 247     Audio Packet ID for the MPEG transport stream (default 256)
 248
 249 ``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
 250     Video Packet ID for the MPEG transport stream (default 260)
 251
 252 ``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
 253     Packet ID for the MPEG transport stream carrying PCR fields (default
 254     259)
 255
 256 ``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
 257     Audio ID for MPEG PES
 258
 259 ``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
 260     Video ID for MPEG PES
 261
 262 .. _v4l2-mpeg-stream-vbi-fmt:
 263
 264 ``V4L2_CID_MPEG_STREAM_VBI_FMT``
 265     (enum)
 266
 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:
 273
 274
 275
 276 .. tabularcolumns:: |p{6 cm}|p{11.5cm}|
 277
 278 .. flat-table::
 279     :header-rows:  0
 280     :stub-columns: 0
 281
 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
 286         sources in the file
 287         ``Documentation/media/v4l-drivers/cx2341x.rst``)
 288
 289
 290
 291 .. _v4l2-mpeg-audio-sampling-freq:
 292
 293 ``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ``
 294     (enum)
 295
 296 enum v4l2_mpeg_audio_sampling_freq -
 297     MPEG Audio sampling frequency. Possible values are:
 298
 299
 300
 301 .. flat-table::
 302     :header-rows:  0
 303     :stub-columns: 0
 304
 305     * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
 306       - 44.1 kHz
 307     * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
 308       - 48 kHz
 309     * - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
 310       - 32 kHz
 311
 312
 313
 314 .. _v4l2-mpeg-audio-encoding:
 315
 316 ``V4L2_CID_MPEG_AUDIO_ENCODING``
 317     (enum)
 318
 319 enum v4l2_mpeg_audio_encoding -
 320     MPEG Audio encoding. This control is specific to multiplexed MPEG
 321     streams. Possible values are:
 322
 323
 324
 325 .. flat-table::
 326     :header-rows:  0
 327     :stub-columns: 0
 328
 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
 339
 340
 341
 342 .. _v4l2-mpeg-audio-l1-bitrate:
 343
 344 ``V4L2_CID_MPEG_AUDIO_L1_BITRATE``
 345     (enum)
 346
 347 enum v4l2_mpeg_audio_l1_bitrate -
 348     MPEG-1/2 Layer I bitrate. Possible values are:
 349
 350
 351
 352 .. flat-table::
 353     :header-rows:  0
 354     :stub-columns: 0
 355
 356     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
 357       - 32 kbit/s
 358     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
 359       - 64 kbit/s
 360     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
 361       - 96 kbit/s
 362     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
 363       - 128 kbit/s
 364     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
 365       - 160 kbit/s
 366     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
 367       - 192 kbit/s
 368     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
 369       - 224 kbit/s
 370     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
 371       - 256 kbit/s
 372     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
 373       - 288 kbit/s
 374     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
 375       - 320 kbit/s
 376     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
 377       - 352 kbit/s
 378     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
 379       - 384 kbit/s
 380     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
 381       - 416 kbit/s
 382     * - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
 383       - 448 kbit/s
 384
 385
 386
 387 .. _v4l2-mpeg-audio-l2-bitrate:
 388
 389 ``V4L2_CID_MPEG_AUDIO_L2_BITRATE``
 390     (enum)
 391
 392 enum v4l2_mpeg_audio_l2_bitrate -
 393     MPEG-1/2 Layer II bitrate. Possible values are:
 394
 395
 396
 397 .. flat-table::
 398     :header-rows:  0
 399     :stub-columns: 0
 400
 401     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
 402       - 32 kbit/s
 403     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
 404       - 48 kbit/s
 405     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
 406       - 56 kbit/s
 407     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
 408       - 64 kbit/s
 409     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
 410       - 80 kbit/s
 411     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
 412       - 96 kbit/s
 413     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
 414       - 112 kbit/s
 415     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
 416       - 128 kbit/s
 417     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
 418       - 160 kbit/s
 419     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
 420       - 192 kbit/s
 421     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
 422       - 224 kbit/s
 423     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
 424       - 256 kbit/s
 425     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
 426       - 320 kbit/s
 427     * - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
 428       - 384 kbit/s
 429
 430
 431
 432 .. _v4l2-mpeg-audio-l3-bitrate:
 433
 434 ``V4L2_CID_MPEG_AUDIO_L3_BITRATE``
 435     (enum)
 436
 437 enum v4l2_mpeg_audio_l3_bitrate -
 438     MPEG-1/2 Layer III bitrate. Possible values are:
 439
 440
 441
 442 .. flat-table::
 443     :header-rows:  0
 444     :stub-columns: 0
 445
 446     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
 447       - 32 kbit/s
 448     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
 449       - 40 kbit/s
 450     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
 451       - 48 kbit/s
 452     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
 453       - 56 kbit/s
 454     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
 455       - 64 kbit/s
 456     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
 457       - 80 kbit/s
 458     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
 459       - 96 kbit/s
 460     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
 461       - 112 kbit/s
 462     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
 463       - 128 kbit/s
 464     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
 465       - 160 kbit/s
 466     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
 467       - 192 kbit/s
 468     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
 469       - 224 kbit/s
 470     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
 471       - 256 kbit/s
 472     * - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
 473       - 320 kbit/s
 474
 475
 476
 477 ``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
 478     AAC bitrate in bits per second.
 479
 480 .. _v4l2-mpeg-audio-ac3-bitrate:
 481
 482 ``V4L2_CID_MPEG_AUDIO_AC3_BITRATE``
 483     (enum)
 484
 485 enum v4l2_mpeg_audio_ac3_bitrate -
 486     AC-3 bitrate. Possible values are:
 487
 488
 489
 490 .. flat-table::
 491     :header-rows:  0
 492     :stub-columns: 0
 493
 494     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
 495       - 32 kbit/s
 496     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
 497       - 40 kbit/s
 498     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
 499       - 48 kbit/s
 500     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
 501       - 56 kbit/s
 502     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
 503       - 64 kbit/s
 504     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
 505       - 80 kbit/s
 506     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
 507       - 96 kbit/s
 508     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
 509       - 112 kbit/s
 510     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
 511       - 128 kbit/s
 512     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
 513       - 160 kbit/s
 514     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
 515       - 192 kbit/s
 516     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
 517       - 224 kbit/s
 518     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
 519       - 256 kbit/s
 520     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
 521       - 320 kbit/s
 522     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
 523       - 384 kbit/s
 524     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
 525       - 448 kbit/s
 526     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
 527       - 512 kbit/s
 528     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
 529       - 576 kbit/s
 530     * - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
 531       - 640 kbit/s
 532
 533
 534
 535 .. _v4l2-mpeg-audio-mode:
 536
 537 ``V4L2_CID_MPEG_AUDIO_MODE``
 538     (enum)
 539
 540 enum v4l2_mpeg_audio_mode -
 541     MPEG Audio mode. Possible values are:
 542
 543
 544
 545 .. flat-table::
 546     :header-rows:  0
 547     :stub-columns: 0
 548
 549     * - ``V4L2_MPEG_AUDIO_MODE_STEREO``
 550       - Stereo
 551     * - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
 552       - Joint Stereo
 553     * - ``V4L2_MPEG_AUDIO_MODE_DUAL``
 554       - Bilingual
 555     * - ``V4L2_MPEG_AUDIO_MODE_MONO``
 556       - Mono
 557
 558
 559
 560 .. _v4l2-mpeg-audio-mode-extension:
 561
 562 ``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION``
 563     (enum)
 564
 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:
 569
 570
 571
 572 .. flat-table::
 573     :header-rows:  0
 574     :stub-columns: 0
 575
 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
 584
 585
 586
 587 .. _v4l2-mpeg-audio-emphasis:
 588
 589 ``V4L2_CID_MPEG_AUDIO_EMPHASIS``
 590     (enum)
 591
 592 enum v4l2_mpeg_audio_emphasis -
 593     Audio Emphasis. Possible values are:
 594
 595
 596
 597 .. flat-table::
 598     :header-rows:  0
 599     :stub-columns: 0
 600
 601     * - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
 602       - None
 603     * - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
 604       - 50/15 microsecond emphasis
 605     * - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
 606       - CCITT J.17
 607
 608
 609
 610 .. _v4l2-mpeg-audio-crc:
 611
 612 ``V4L2_CID_MPEG_AUDIO_CRC``
 613     (enum)
 614
 615 enum v4l2_mpeg_audio_crc -
 616     CRC method. Possible values are:
 617
 618
 619
 620 .. flat-table::
 621     :header-rows:  0
 622     :stub-columns: 0
 623
 624     * - ``V4L2_MPEG_AUDIO_CRC_NONE``
 625       - None
 626     * - ``V4L2_MPEG_AUDIO_CRC_CRC16``
 627       - 16 bit parity check
 628
 629
 630
 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 =
 635     unmuted, 1 = muted.
 636
 637 .. _v4l2-mpeg-audio-dec-playback:
 638
 639 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK``
 640     (enum)
 641
 642 enum v4l2_mpeg_audio_dec_playback -
 643     Determines how monolingual audio should be played back. Possible
 644     values are:
 645
 646
 647
 648 .. tabularcolumns:: |p{9.0cm}|p{8.5cm}|
 649
 650 .. flat-table::
 651     :header-rows:  0
 652     :stub-columns: 0
 653
 654     * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
 655       - Automatically determines the best playback mode.
 656     * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
 657       - Stereo playback.
 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``
 663       - Mono playback.
 664     * - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
 665       - Stereo playback with swapped left and right channels.
 666
 667
 668
 669 .. _v4l2-mpeg-audio-dec-multilingual-playback:
 670
 671 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK``
 672     (enum)
 673
 674 enum v4l2_mpeg_audio_dec_playback -
 675     Determines how multilingual audio should be played back.
 676
 677 .. _v4l2-mpeg-video-encoding:
 678
 679 ``V4L2_CID_MPEG_VIDEO_ENCODING``
 680     (enum)
 681
 682 enum v4l2_mpeg_video_encoding -
 683     MPEG Video encoding method. This control is specific to multiplexed
 684     MPEG streams. Possible values are:
 685
 686
 687
 688 .. flat-table::
 689     :header-rows:  0
 690     :stub-columns: 0
 691
 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
 698
 699
 700
 701 .. _v4l2-mpeg-video-aspect:
 702
 703 ``V4L2_CID_MPEG_VIDEO_ASPECT``
 704     (enum)
 705
 706 enum v4l2_mpeg_video_aspect -
 707     Video aspect. Possible values are:
 708
 709
 710
 711 .. flat-table::
 712     :header-rows:  0
 713     :stub-columns: 0
 714
 715     * - ``V4L2_MPEG_VIDEO_ASPECT_1x1``
 716     * - ``V4L2_MPEG_VIDEO_ASPECT_4x3``
 717     * - ``V4L2_MPEG_VIDEO_ASPECT_16x9``
 718     * - ``V4L2_MPEG_VIDEO_ASPECT_221x100``
 719
 720
 721
 722 ``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
 723     Number of B-Frames (default 2)
 724
 725 ``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
 726     GOP size (default 12)
 727
 728 ``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
 729     GOP closure (default 1)
 730
 731 ``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
 732     Enable 3:2 pulldown (default 0)
 733
 734 .. _v4l2-mpeg-video-bitrate-mode:
 735
 736 ``V4L2_CID_MPEG_VIDEO_BITRATE_MODE``
 737     (enum)
 738
 739 enum v4l2_mpeg_video_bitrate_mode -
 740     Video bitrate mode. Possible values are:
 741
 742
 743
 744 .. flat-table::
 745     :header-rows:  0
 746     :stub-columns: 0
 747
 748     * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
 749       - Variable bitrate
 750     * - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
 751       - Constant bitrate
 752
 753
 754
 755 ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
 756     Video bitrate in bits per second.
 757
 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.
 762
 763 ``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)``
 764     For every captured frame, skip this many subsequent frames (default
 765     0).
 766
 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 =
 770     muted.
 771
 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):
 775
 776
 777
 778 .. flat-table::
 779     :header-rows:  0
 780     :stub-columns: 0
 781
 782     * - Bit 0:7
 783       - V chrominance information
 784     * - Bit 8:15
 785       - U chrominance information
 786     * - Bit 16:23
 787       - Y luminance information
 788     * - Bit 24:31
 789       - Must be zero.
 790
 791
 792
 793 .. _v4l2-mpeg-video-dec-pts:
 794
 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`.
 800
 801 .. _v4l2-mpeg-video-dec-frame:
 802
 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.
 807
 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.
 812
 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.
 816
 817 .. _v4l2-mpeg-video-h264-vui-sar-idc:
 818
 819 ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC``
 820     (enum)
 821
 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
 825     encoder.
 826
 827
 828
 829 .. flat-table::
 830     :header-rows:  0
 831     :stub-columns: 0
 832
 833     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
 834       - Unspecified
 835     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
 836       - 1x1
 837     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
 838       - 12x11
 839     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
 840       - 10x11
 841     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
 842       - 16x11
 843     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
 844       - 40x33
 845     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
 846       - 24x11
 847     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
 848       - 20x11
 849     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
 850       - 32x11
 851     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
 852       - 80x33
 853     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
 854       - 18x11
 855     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
 856       - 15x11
 857     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
 858       - 64x33
 859     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
 860       - 160x99
 861     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
 862       - 4x3
 863     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
 864       - 3x2
 865     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
 866       - 2x1
 867     * - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
 868       - Extended SAR
 869
 870
 871
 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.
 875
 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.
 879
 880 .. _v4l2-mpeg-video-h264-level:
 881
 882 ``V4L2_CID_MPEG_VIDEO_H264_LEVEL``
 883     (enum)
 884
 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:
 888
 889
 890
 891 .. flat-table::
 892     :header-rows:  0
 893     :stub-columns: 0
 894
 895     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
 896       - Level 1.0
 897     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
 898       - Level 1B
 899     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
 900       - Level 1.1
 901     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
 902       - Level 1.2
 903     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
 904       - Level 1.3
 905     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
 906       - Level 2.0
 907     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
 908       - Level 2.1
 909     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
 910       - Level 2.2
 911     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
 912       - Level 3.0
 913     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
 914       - Level 3.1
 915     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
 916       - Level 3.2
 917     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
 918       - Level 4.0
 919     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
 920       - Level 4.1
 921     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
 922       - Level 4.2
 923     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
 924       - Level 5.0
 925     * - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
 926       - Level 5.1
 927
 928
 929
 930 .. _v4l2-mpeg-video-mpeg4-level:
 931
 932 ``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL``
 933     (enum)
 934
 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:
 938
 939
 940
 941 .. flat-table::
 942     :header-rows:  0
 943     :stub-columns: 0
 944
 945     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0``
 946       - Level 0
 947     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_0B``
 948       - Level 0b
 949     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_1``
 950       - Level 1
 951     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_2``
 952       - Level 2
 953     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3``
 954       - Level 3
 955     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_3B``
 956       - Level 3b
 957     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_4``
 958       - Level 4
 959     * - ``V4L2_MPEG_VIDEO_MPEG4_LEVEL_5``
 960       - Level 5
 961
 962
 963
 964 .. _v4l2-mpeg-video-h264-profile:
 965
 966 ``V4L2_CID_MPEG_VIDEO_H264_PROFILE``
 967     (enum)
 968
 969 enum v4l2_mpeg_video_h264_profile -
 970     The profile information for H264. Applicable to the H264 encoder.
 971     Possible values are:
 972
 973
 974
 975 .. flat-table::
 976     :header-rows:  0
 977     :stub-columns: 0
 978
 979     * - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
 980       - Baseline profile
 981     * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
 982       - Constrained Baseline profile
 983     * - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
 984       - Main profile
 985     * - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
 986       - Extended profile
 987     * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
 988       - High profile
 989     * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
 990       - High 10 profile
 991     * - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
 992       - High 422 profile
 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
1013
1014
1015
1016 .. _v4l2-mpeg-video-mpeg4-profile:
1017
1018 ``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE``
1019     (enum)
1020
1021 enum v4l2_mpeg_video_mpeg4_profile -
1022     The profile information for MPEG4. Applicable to the MPEG4 encoder.
1023     Possible values are:
1024
1025
1026
1027 .. flat-table::
1028     :header-rows:  0
1029     :stub-columns: 0
1030
1031     * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE``
1032       - Simple profile
1033     * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_SIMPLE``
1034       - Advanced Simple profile
1035     * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_CORE``
1036       - Core profile
1037     * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE``
1038       - Simple Scalable profile
1039     * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY``
1040       -
1041
1042
1043
1044 ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
1045     The maximum number of reference pictures used for encoding.
1046     Applicable to the encoder.
1047
1048 .. _v4l2-mpeg-video-multi-slice-mode:
1049
1050 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE``
1051     (enum)
1052
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:
1056
1057
1058
1059 .. tabularcolumns:: |p{8.7cm}|p{8.8cm}|
1060
1061 .. flat-table::
1062     :header-rows:  0
1063     :stub-columns: 0
1064
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.
1071
1072
1073
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
1078     encoder.
1079
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
1084     encoder.
1085
1086 .. _v4l2-mpeg-video-h264-loop-filter-mode:
1087
1088 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE``
1089     (enum)
1090
1091 enum v4l2_mpeg_video_h264_loop_filter_mode -
1092     Loop filter mode for H264 encoder. Possible values are:
1093
1094
1095
1096 .. tabularcolumns:: |p{14.0cm}|p{3.5cm}|
1097
1098 .. flat-table::
1099     :header-rows:  0
1100     :stub-columns: 0
1101
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.
1108
1109
1110
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.
1114
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.
1118
1119 .. _v4l2-mpeg-video-h264-entropy-mode:
1120
1121 ``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE``
1122     (enum)
1123
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:
1127
1128
1129
1130 .. flat-table::
1131     :header-rows:  0
1132     :stub-columns: 0
1133
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.
1138
1139
1140
1141 ``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
1142     Enable 8X8 transform for H264. Applicable to the H264 encoder.
1143
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.
1149
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.
1159
1160 ``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
1161     Macroblock level rate control enable. Applicable to the MPEG4 and
1162     H264 encoders.
1163
1164 ``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
1165     Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
1166     encoder.
1167
1168 ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
1169     Quantization parameter for an I frame for H263. Valid range: from 1
1170     to 31.
1171
1172 ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
1173     Minimum quantization parameter for H263. Valid range: from 1 to 31.
1174
1175 ``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
1176     Maximum quantization parameter for H263. Valid range: from 1 to 31.
1177
1178 ``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
1179     Quantization parameter for an P frame for H263. Valid range: from 1
1180     to 31.
1181
1182 ``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
1183     Quantization parameter for an B frame for H263. Valid range: from 1
1184     to 31.
1185
1186 ``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
1187     Quantization parameter for an I frame for H264. Valid range: from 0
1188     to 51.
1189
1190 ``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
1191     Minimum quantization parameter for H264. Valid range: from 0 to 51.
1192
1193 ``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
1194     Maximum quantization parameter for H264. Valid range: from 0 to 51.
1195
1196 ``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
1197     Quantization parameter for an P frame for H264. Valid range: from 0
1198     to 51.
1199
1200 ``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
1201     Quantization parameter for an B frame for H264. Valid range: from 0
1202     to 51.
1203
1204 ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
1205     Quantization parameter for an I frame for MPEG4. Valid range: from 1
1206     to 31.
1207
1208 ``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
1209     Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
1210
1211 ``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
1212     Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
1213
1214 ``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
1215     Quantization parameter for an P frame for MPEG4. Valid range: from 1
1216     to 31.
1217
1218 ``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
1219     Quantization parameter for an B frame for MPEG4. Valid range: from 1
1220     to 31.
1221
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.
1231
1232 .. _v4l2-mpeg-video-vbv-delay:
1233
1234 ``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
1235     Sets the initial delay in milliseconds for VBV buffer control.
1236
1237 .. _v4l2-mpeg-video-hor-search-range:
1238
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.
1244
1245 .. _v4l2-mpeg-video-vert-search-range:
1246
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.
1252
1253 .. _v4l2-mpeg-video-force-key-frame:
1254
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.
1258
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.
1264
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
1273     H264 encoder.
1274
1275 .. _v4l2-mpeg-video-header-mode:
1276
1277 ``V4L2_CID_MPEG_VIDEO_HEADER_MODE``
1278     (enum)
1279
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:
1284
1285
1286
1287 .. tabularcolumns:: |p{10.3cm}|p{7.2cm}|
1288
1289 .. flat-table::
1290     :header-rows:  0
1291     :stub-columns: 0
1292
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
1297         frame.
1298
1299
1300
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
1304     and 4 encoder.
1305
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.
1309
1310 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
1311     vop_time_increment_resolution value for MPEG4. Applicable to the
1312     MPEG4 encoder.
1313
1314 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
1315     vop_time_increment value for MPEG4. Applicable to the MPEG4
1316     encoder.
1317
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.
1323
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
1326     H264 encoder.
1327
1328 .. _v4l2-mpeg-video-h264-sei-fp-arrangement-type:
1329
1330 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE``
1331     (enum)
1332
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:
1336
1337 .. tabularcolumns:: |p{12cm}|p{5.5cm}|
1338
1339 .. flat-table::
1340     :header-rows:  0
1341     :stub-columns: 0
1342
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.
1355
1356
1357
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.
1362
1363 .. _v4l2-mpeg-video-h264-fmo-map-type:
1364
1365 ``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE``
1366    (enum)
1367
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
1371     values are:
1372
1373 .. tabularcolumns:: |p{12.5cm}|p{5.0cm}|
1374
1375 .. flat-table::
1376     :header-rows:  0
1377     :stub-columns: 0
1378
1379     * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
1380       - Slices are interleaved one after other with macroblocks in run
1381         length order.
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.
1395
1396
1397
1398 ``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
1399     Number of slice groups in FMO. Applicable to the H264 encoder.
1400
1401 .. _v4l2-mpeg-video-h264-fmo-change-direction:
1402
1403 ``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION``
1404     (enum)
1405
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:
1409
1410
1411
1412 .. flat-table::
1413     :header-rows:  0
1414     :stub-columns: 0
1415
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.
1420
1421
1422
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.
1426
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.
1430
1431 ``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
1432     Enables arbitrary slice ordering in encoded bitstream. Applicable to
1433     the H264 encoder.
1434
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
1438     significant bit):
1439
1440
1441
1442 .. flat-table::
1443     :header-rows:  0
1444     :stub-columns: 0
1445
1446     * - Bit 0:15
1447       - Slice ID
1448     * - Bit 16:32
1449       - Slice position or order
1450
1451
1452
1453 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
1454     Enables H264 hierarchical coding. Applicable to the H264 encoder.
1455
1456 .. _v4l2-mpeg-video-h264-hierarchical-coding-type:
1457
1458 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE``
1459     (enum)
1460
1461 enum v4l2_mpeg_video_h264_hierarchical_coding_type -
1462     Specifies the hierarchical coding type. Applicable to the H264
1463     encoder. Possible values are:
1464
1465
1466
1467 .. flat-table::
1468     :header-rows:  0
1469     :stub-columns: 0
1470
1471     * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
1472       - Hierarchical B coding.
1473     * - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
1474       - Hierarchical P coding.
1475
1476
1477
1478 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
1479     Specifies the number of hierarchical coding layers. Applicable to
1480     the H264 encoder.
1481
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):
1486
1487
1488
1489 .. flat-table::
1490     :header-rows:  0
1491     :stub-columns: 0
1492
1493     * - Bit 0:15
1494       - QP value
1495     * - Bit 16:32
1496       - Layer number
1497
1498
1499
1500
1501 MFC 5.1 MPEG Controls
1502 ---------------------
1503
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.
1507
1508
1509 .. _mfc51-control-id:
1510
1511 MFC 5.1 Control IDs
1512 ^^^^^^^^^^^^^^^^^^^
1513
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.
1521
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.
1528
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.
1532
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.
1536
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
1540     bit):
1541
1542
1543
1544 .. flat-table::
1545     :header-rows:  0
1546     :stub-columns: 0
1547
1548     * - Bit 0:7
1549       - V chrominance information
1550     * - Bit 8:15
1551       - U chrominance information
1552     * - Bit 16:23
1553       - Y luminance information
1554     * - Bit 24:31
1555       - Must be zero.
1556
1557
1558
1559 ``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
1560     Reaction coefficient for MFC rate control. Applicable to encoders.
1561
1562     .. note::
1563
1564        #. Valid only when the frame level RC is enabled.
1565
1566        #. For tight CBR, this field must be small (ex. 2 ~ 10). For
1567           VBR, this field must be large (ex. 100 ~ 1000).
1568
1569        #. It is not recommended to use the greater number than
1570           FRAME_RATE * (10^9 / BIT_RATE).
1571
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
1576     encoder.
1577
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
1582     encoder.
1583
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
1588     encoder.
1589
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
1594     encoder.
1595
1596 .. _v4l2-mpeg-mfc51-video-frame-skip-mode:
1597
1598 ``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE``
1599     (enum)
1600
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
1605     are:
1606
1607
1608 .. tabularcolumns:: |p{9.0cm}|p{8.5cm}|
1609
1610 .. flat-table::
1611     :header-rows:  0
1612     :stub-columns: 0
1613
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.
1622
1623
1624
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.
1636
1637 .. _v4l2-mpeg-mfc51-video-force-frame-type:
1638
1639 ``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE``
1640     (enum)
1641
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:
1645
1646
1647
1648 .. flat-table::
1649     :header-rows:  0
1650     :stub-columns: 0
1651
1652     * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
1653       - Forcing a specific frame type disabled.
1654     * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
1655       - Force an I-frame.
1656     * - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
1657       - Force a non-coded frame.
1658
1659
1660
1661
1662 CX2341x MPEG Controls
1663 ---------------------
1664
1665 The following MPEG class controls deal with MPEG encoding settings that
1666 are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
1667
1668
1669 .. _cx2341x-control-id:
1670
1671 CX2341x Control IDs
1672 ^^^^^^^^^^^^^^^^^^^
1673
1674 .. _v4l2-mpeg-cx2341x-video-spatial-filter-mode:
1675
1676 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE``
1677     (enum)
1678
1679 enum v4l2_mpeg_cx2341x_video_spatial_filter_mode -
1680     Sets the Spatial Filter mode (default ``MANUAL``). Possible values
1681     are:
1682
1683
1684
1685 .. flat-table::
1686     :header-rows:  0
1687     :stub-columns: 0
1688
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
1693
1694
1695
1696 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
1697     The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
1698     is 0.)
1699
1700 .. _luma-spatial-filter-type:
1701
1702 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE``
1703     (enum)
1704
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:
1708
1709
1710
1711 .. tabularcolumns:: |p{14.5cm}|p{3.0cm}|
1712
1713 .. flat-table::
1714     :header-rows:  0
1715     :stub-columns: 0
1716
1717     * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
1718       - No filter
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
1727
1728
1729
1730 .. _chroma-spatial-filter-type:
1731
1732 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE``
1733     (enum)
1734
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:
1738
1739
1740
1741 .. flat-table::
1742     :header-rows:  0
1743     :stub-columns: 0
1744
1745     * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
1746       - No filter
1747     * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
1748       - One-dimensional horizontal
1749
1750
1751
1752 .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode:
1753
1754 ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE``
1755     (enum)
1756
1757 enum v4l2_mpeg_cx2341x_video_temporal_filter_mode -
1758     Sets the Temporal Filter mode (default ``MANUAL``). Possible values
1759     are:
1760
1761
1762
1763 .. flat-table::
1764     :header-rows:  0
1765     :stub-columns: 0
1766
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
1771
1772
1773
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.)
1777
1778 .. _v4l2-mpeg-cx2341x-video-median-filter-type:
1779
1780 ``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE``
1781     (enum)
1782
1783 enum v4l2_mpeg_cx2341x_video_median_filter_type -
1784     Median Filter Type (default ``OFF``). Possible values are:
1785
1786
1787
1788 .. flat-table::
1789     :header-rows:  0
1790     :stub-columns: 0
1791
1792     * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
1793       - No filter
1794     * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
1795       - Horizontal filter
1796     * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
1797       - Vertical filter
1798     * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
1799       - Horizontal and vertical filter
1800     * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
1801       - Diagonal filter
1802
1803
1804
1805 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
1806     Threshold above which the luminance median filter is enabled
1807     (default 0)
1808
1809 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
1810     Threshold below which the luminance median filter is enabled
1811     (default 255)
1812
1813 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
1814     Threshold above which the chroma median filter is enabled (default
1815     0)
1816
1817 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
1818     Threshold below which the chroma median filter is enabled (default
1819     255)
1820
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.
1828
1829
1830 VPX Control Reference
1831 ---------------------
1832
1833 The VPX controls include controls for encoding parameters of VPx video
1834 codec.
1835
1836
1837 .. _vpx-control-id:
1838
1839 VPX Control IDs
1840 ^^^^^^^^^^^^^^^
1841
1842 .. _v4l2-vpx-num-partitions:
1843
1844 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS``
1845     (enum)
1846
1847 enum v4l2_vp8_num_partitions -
1848     The number of token partitions to use in VP8 encoder. Possible
1849     values are:
1850
1851
1852
1853 .. flat-table::
1854     :header-rows:  0
1855     :stub-columns: 0
1856
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
1865
1866
1867
1868 ``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
1869     Setting this prevents intra 4x4 mode in the intra mode decision.
1870
1871 .. _v4l2-vpx-num-ref-frames:
1872
1873 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES``
1874     (enum)
1875
1876 enum v4l2_vp8_num_ref_frames -
1877     The number of reference pictures for encoding P frames. Possible
1878     values are:
1879
1880 .. tabularcolumns:: |p{7.9cm}|p{9.6cm}|
1881
1882 .. flat-table::
1883     :header-rows:  0
1884     :stub-columns: 0
1885
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
1894         be searched.
1895
1896
1897
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
1901     value.
1902
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.
1906
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.
1914
1915 .. _v4l2-vpx-golden-frame-sel:
1916
1917 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL``
1918     (enum)
1919
1920 enum v4l2_vp8_golden_frame_sel -
1921     Selects the golden frame for encoding. Possible values are:
1922
1923 .. raw:: latex
1924
1925     \footnotesize
1926
1927 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
1928
1929 .. flat-table::
1930     :header-rows:  0
1931     :stub-columns: 0
1932
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
1935         'n'.
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
1939         golden frame.
1940
1941 .. raw:: latex
1942
1943     \normalsize
1944
1945
1946 ``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
1947     Minimum quantization parameter for VP8.
1948
1949 ``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
1950     Maximum quantization parameter for VP8.
1951
1952 ``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
1953     Quantization parameter for an I frame for VP8.
1954
1955 ``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
1956     Quantization parameter for a P frame for VP8.
1957
1958 .. _v4l2-mpeg-video-vp8-profile:
1959
1960 ``V4L2_CID_MPEG_VIDEO_VP8_PROFILE``
1961     (enum)
1962
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:
1967
1968 .. flat-table::
1969     :header-rows:  0
1970     :stub-columns: 0
1971
1972     * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_0``
1973       - Profile 0
1974     * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_1``
1975       - Profile 1
1976     * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_2``
1977       - Profile 2
1978     * - ``V4L2_MPEG_VIDEO_VP8_PROFILE_3``
1979       - Profile 3
1980
1981 .. _v4l2-mpeg-video-vp9-profile:
1982
1983 ``V4L2_CID_MPEG_VIDEO_VP9_PROFILE``
1984     (enum)
1985
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:
1990
1991 .. flat-table::
1992     :header-rows:  0
1993     :stub-columns: 0
1994
1995     * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_0``
1996       - Profile 0
1997     * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_1``
1998       - Profile 1
1999     * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_2``
2000       - Profile 2
2001     * - ``V4L2_MPEG_VIDEO_VP9_PROFILE_3``
2002       - Profile 3
2003
2004
2005 High Efficiency Video Coding (HEVC/H.265) Control Reference
2006 -----------------------------------------------------------
2007
2008 The HEVC/H.265 controls include controls for encoding parameters of HEVC/H.265
2009 video codec.
2010
2011
2012 .. _hevc-control-id:
2013
2014 HEVC/H.265 Control IDs
2015 ^^^^^^^^^^^^^^^^^^^^^^
2016
2017 ``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)``
2018     Minimum quantization parameter for HEVC.
2019     Valid range: from 0 to 51.
2020
2021 ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)``
2022     Maximum quantization parameter for HEVC.
2023     Valid range: from 0 to 51.
2024
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].
2029
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].
2034
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].
2039
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.
2045
2046 .. _v4l2-hevc-hier-coding-type:
2047
2048 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_TYPE``
2049     (enum)
2050
2051 enum v4l2_mpeg_video_hevc_hier_coding_type -
2052     Selects the hierarchical coding type for encoding. Possible values are:
2053
2054 .. raw:: latex
2055
2056     \footnotesize
2057
2058 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2059
2060 .. flat-table::
2061     :header-rows:  0
2062     :stub-columns: 0
2063
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.
2068
2069 .. raw:: latex
2070
2071     \normalsize
2072
2073
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
2078     LAYER 1 and so on.
2079
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].
2084
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].
2089
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].
2094
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].
2099
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].
2104
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].
2109
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].
2114
2115 .. _v4l2-hevc-profile:
2116
2117 ``V4L2_CID_MPEG_VIDEO_HEVC_PROFILE``
2118     (enum)
2119
2120 enum v4l2_mpeg_video_hevc_profile -
2121     Select the desired profile for HEVC encoder.
2122
2123 .. raw:: latex
2124
2125     \footnotesize
2126
2127 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2128
2129 .. flat-table::
2130     :header-rows:  0
2131     :stub-columns: 0
2132
2133     * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN``
2134       - Main profile.
2135     * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_STILL_PICTURE``
2136       - Main still picture profile.
2137     * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_10``
2138       - Main 10 profile.
2139
2140 .. raw:: latex
2141
2142     \normalsize
2143
2144
2145 .. _v4l2-hevc-level:
2146
2147 ``V4L2_CID_MPEG_VIDEO_HEVC_LEVEL``
2148     (enum)
2149
2150 enum v4l2_mpeg_video_hevc_level -
2151     Selects the desired level for HEVC encoder.
2152
2153 .. raw:: latex
2154
2155     \footnotesize
2156
2157 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2158
2159 .. flat-table::
2160     :header-rows:  0
2161     :stub-columns: 0
2162
2163     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1``
2164       - Level 1.0
2165     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2``
2166       - Level 2.0
2167     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1``
2168       - Level 2.1
2169     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3``
2170       - Level 3.0
2171     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1``
2172       - Level 3.1
2173     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4``
2174       - Level 4.0
2175     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1``
2176       - Level 4.1
2177     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5``
2178       - Level 5.0
2179     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1``
2180       - Level 5.1
2181     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2``
2182       - Level 5.2
2183     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6``
2184       - Level 6.0
2185     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1``
2186       - Level 6.1
2187     * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2``
2188       - Level 6.2
2189
2190 .. raw:: latex
2191
2192     \normalsize
2193
2194
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.
2199
2200 .. _v4l2-hevc-tier:
2201
2202 ``V4L2_CID_MPEG_VIDEO_HEVC_TIER``
2203     (enum)
2204
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
2210     high bit rates.
2211
2212 .. raw:: latex
2213
2214     \footnotesize
2215
2216 .. tabularcolumns:: |p{9.0cm}|p{8.0cm}|
2217
2218 .. flat-table::
2219     :header-rows:  0
2220     :stub-columns: 0
2221
2222     * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN``
2223       - Main tier.
2224     * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH``
2225       - High tier.
2226
2227 .. raw:: latex
2228
2229     \normalsize
2230
2231
2232 ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)``
2233     Selects HEVC maximum coding unit depth.
2234
2235 .. _v4l2-hevc-loop-filter-mode:
2236
2237 ``V4L2_CID_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE``
2238     (enum)
2239
2240 enum v4l2_mpeg_video_hevc_loop_filter_mode -
2241     Loop filter mode for HEVC encoder. Possible values are:
2242
2243 .. raw:: latex
2244
2245     \footnotesize
2246
2247 .. tabularcolumns:: |p{10.7cm}|p{6.3cm}|
2248
2249 .. flat-table::
2250     :header-rows:  0
2251     :stub-columns: 0
2252
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.
2259
2260 .. raw:: latex
2261
2262     \normalsize
2263
2264
2265 ``V4L2_CID_MPEG_VIDEO_HEVC_LF_BETA_OFFSET_DIV2 (integer)``
2266     Selects HEVC loop filter beta offset. The valid range is [-6, +6].
2267
2268 ``V4L2_CID_MPEG_VIDEO_HEVC_LF_TC_OFFSET_DIV2 (integer)``
2269     Selects HEVC loop filter tc offset. The valid range is [-6, +6].
2270
2271 .. _v4l2-hevc-refresh-type:
2272
2273 ``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_TYPE``
2274     (enum)
2275
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.
2280
2281 .. raw:: latex
2282
2283     \footnotesize
2284
2285 .. tabularcolumns:: |p{8.0cm}|p{9.0cm}|
2286
2287 .. flat-table::
2288     :header-rows:  0
2289     :stub-columns: 0
2290
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.
2297
2298 .. raw:: latex
2299
2300     \normalsize
2301
2302
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.
2307
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.
2311
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.
2318
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
2322     processing.
2323
2324 ``V4L2_CID_MPEG_VIDEO_HEVC_GENERAL_PB (boolean)``
2325     Setting the value to 1 enables combination of P and B frame for HEVC
2326     encoder.
2327
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.
2331
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.
2336
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.
2340
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.
2344
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.
2351
2352 .. _v4l2-hevc-size-of-length-field:
2353
2354 ``V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD``
2355 (enum)
2356
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.
2360
2361 .. raw:: latex
2362
2363     \footnotesize
2364
2365 .. tabularcolumns:: |p{6.0cm}|p{11.0cm}|
2366
2367 .. flat-table::
2368     :header-rows:  0
2369     :stub-columns: 0
2370
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.
2379
2380 .. raw:: latex
2381
2382     \normalsize
2383
2384 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_BR (integer)``
2385     Indicates bit rate for hierarchical coding layer 0 for HEVC encoder.
2386
2387 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_BR (integer)``
2388     Indicates bit rate for hierarchical coding layer 1 for HEVC encoder.
2389
2390 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_BR (integer)``
2391     Indicates bit rate for hierarchical coding layer 2 for HEVC encoder.
2392
2393 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_BR (integer)``
2394     Indicates bit rate for hierarchical coding layer 3 for HEVC encoder.
2395
2396 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_BR (integer)``
2397     Indicates bit rate for hierarchical coding layer 4 for HEVC encoder.
2398
2399 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_BR (integer)``
2400     Indicates bit rate for hierarchical coding layer 5 for HEVC encoder.
2401
2402 ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_BR (integer)``
2403     Indicates bit rate for hierarchical coding layer 6 for HEVC encoder.
2404
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.
2408
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.
2413
2414
2415 .. _camera-controls:
2416
2417 Camera Control Reference
2418 ========================
2419
2420 The Camera class includes controls for mechanical (or equivalent
2421 digital) features of a device such as controllable lenses or sensors.
2422
2423
2424 .. _camera-control-id:
2425
2426 Camera Control IDs
2427 ------------------
2428
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.
2433
2434 .. _v4l2-exposure-auto-type:
2435
2436 ``V4L2_CID_EXPOSURE_AUTO``
2437     (enum)
2438
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:
2444
2445
2446
2447 .. flat-table::
2448     :header-rows:  0
2449     :stub-columns: 0
2450
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.
2459
2460
2461
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.
2467
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.
2473
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.
2480
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.
2485
2486 .. _v4l2-exposure-metering:
2487
2488 ``V4L2_CID_EXPOSURE_METERING``
2489     (enum)
2490
2491 enum v4l2_exposure_metering -
2492     Determines how the camera measures the amount of light available for
2493     the frame exposure. Possible values are:
2494
2495 .. tabularcolumns:: |p{8.5cm}|p{9.0cm}|
2496
2497 .. flat-table::
2498     :header-rows:  0
2499     :stub-columns: 0
2500
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.
2514
2515
2516
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
2522     control.
2523
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.
2529
2530 ``V4L2_CID_PAN_RESET (button)``
2531     When this control is set, the camera moves horizontally to the
2532     default position.
2533
2534 ``V4L2_CID_TILT_RESET (button)``
2535     When this control is set, the camera moves vertically to the default
2536     position.
2537
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.
2544
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.
2550
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.
2555
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
2560     write-only control.
2561
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.
2566
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.
2571
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
2576     ``FALSE`` (0).
2577
2578 .. _v4l2-auto-focus-status:
2579
2580 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
2581     The automatic focus status. This is a read-only control.
2582
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``
2585     control value.
2586
2587 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
2588
2589 .. flat-table::
2590     :header-rows:  0
2591     :stub-columns: 0
2592
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.
2602
2603
2604
2605 .. _v4l2-auto-focus-range:
2606
2607 ``V4L2_CID_AUTO_FOCUS_RANGE``
2608     (enum)
2609
2610 enum v4l2_auto_focus_range -
2611     Determines auto focus distance range for which lens may be adjusted.
2612
2613 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
2614
2615 .. flat-table::
2616     :header-rows:  0
2617     :stub-columns: 0
2618
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
2623         performance.
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.
2629
2630
2631
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
2635     integer.
2636
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
2642     control.
2643
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.
2651
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
2655     close it.
2656
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
2661     write-only control.
2662
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.
2670
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.
2675
2676 .. _v4l2-auto-n-preset-white-balance:
2677
2678 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
2679     (enum)
2680
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.
2687
2688 .. tabularcolumns:: |p{7.0 cm}|p{10.5cm}|
2689
2690 .. flat-table::
2691     :header-rows:  0
2692     :stub-columns: 0
2693
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
2707         lighting.
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
2721         range.
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.
2725
2726
2727
2728 .. _v4l2-wide-dynamic-range:
2729
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]_
2737
2738 .. _v4l2-image-stabilization:
2739
2740 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
2741     Enables or disables image stabilization.
2742
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.
2755
2756 .. _v4l2-iso-sensitivity-auto-type:
2757
2758 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
2759     (enum)
2760
2761 enum v4l2_iso_sensitivity_type -
2762     Enables or disables automatic ISO sensitivity adjustments.
2763
2764
2765
2766 .. flat-table::
2767     :header-rows:  0
2768     :stub-columns: 0
2769
2770     * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
2771       - Manual ISO sensitivity.
2772     * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
2773       - Automatic ISO sensitivity adjustments.
2774
2775
2776
2777 .. _v4l2-scene-mode:
2778
2779 ``V4L2_CID_SCENE_MODE``
2780     (enum)
2781
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.
2789
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:
2793
2794 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
2795
2796 .. flat-table::
2797     :header-rows:  0
2798     :stub-columns: 0
2799
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
2825         and yellows.
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
2829         stabilization.
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
2859         up the saturation.
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.
2865
2866
2867
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
2873     are defined:
2874
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
2880     focus controls.
2881
2882
2883
2884 .. flat-table::
2885     :header-rows:  0
2886     :stub-columns: 0
2887
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.
2894
2895
2896
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.
2903
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.
2909
2910
2911 .. _fm-tx-controls:
2912
2913 FM Transmitter Control Reference
2914 ================================
2915
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.
2920
2921
2922 .. _fm-tx-control-id:
2923
2924 FM_TX Control IDs
2925 -----------------
2926
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.
2931
2932 ``V4L2_CID_RDS_TX_DEVIATION (integer)``
2933     Configures RDS signal frequency deviation level in Hz. The range and
2934     step are driver-specific.
2935
2936 ``V4L2_CID_RDS_TX_PI (integer)``
2937     Sets the RDS Programme Identification field for transmission.
2938
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.
2942
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.
2954
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
2968     32 or 64.
2969
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.
2973
2974 ``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
2975     Sets the
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.
2979
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.
2983
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.
2987
2988 ``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
2989     If set, then a traffic announcement is in progress.
2990
2991 ``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
2992     If set, then the tuned programme carries traffic announcements.
2993
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.
2998
2999 ``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
3000     If set, then transmit alternate frequencies.
3001
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.
3006
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.
3011
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.
3015
3016 ``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
3017     Configures audio frequency deviation level in Hz. The range and step
3018     are driver-specific.
3019
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 +
3024     Threshold).
3025
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.
3029
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.
3033
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.
3037
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.
3041
3042 ``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
3043     Enables or disables the pilot tone generation feature.
3044
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.
3048
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.
3052
3053 ``V4L2_CID_TUNE_PREEMPHASIS``
3054     (enum)
3055
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:
3062
3063
3064
3065 .. flat-table::
3066     :header-rows:  0
3067     :stub-columns: 0
3068
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.
3075
3076
3077
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.
3081
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
3085     driver-specific.
3086
3087 For more details about RDS specification, refer to :ref:`iec62106`
3088 document, from CENELEC.
3089
3090
3091 .. _flash-controls:
3092
3093 Flash Control Reference
3094 =======================
3095
3096 The V4L2 flash controls are intended to provide generic access to flash
3097 controller devices. Flash controller devices are typically used in
3098 digital cameras.
3099
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.
3102
3103
3104 .. _flash-controls-use-cases:
3105
3106 Supported use cases
3107 -------------------
3108
3109
3110 Unsynchronised LED flash (software strobe)
3111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3112
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.
3117
3118 Example of such device: Nokia N900.
3119
3120
3121 Synchronised LED flash (hardware strobe)
3122 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3123
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.
3127
3128 The sensor controls the flash duration and timing. This information
3129 typically must be made available to the sensor.
3130
3131
3132 LED flash as torch
3133 ^^^^^^^^^^^^^^^^^^
3134
3135 LED flash may be used as torch in conjunction with another use case
3136 involving camera or individually.
3137
3138
3139 .. _flash-control-id:
3140
3141 Flash Control IDs
3142 """""""""""""""""
3143
3144 ``V4L2_CID_FLASH_CLASS (class)``
3145     The FLASH class descriptor.
3146
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.
3151
3152
3153
3154 .. flat-table::
3155     :header-rows:  0
3156     :stub-columns: 0
3157
3158     * - ``V4L2_FLASH_LED_MODE_NONE``
3159       - Off.
3160     * - ``V4L2_FLASH_LED_MODE_FLASH``
3161       - Flash mode.
3162     * - ``V4L2_FLASH_LED_MODE_TORCH``
3163       - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
3164
3165
3166
3167 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
3168     Defines the source of the flash LED strobe.
3169
3170 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3171
3172 .. flat-table::
3173     :header-rows:  0
3174     :stub-columns: 0
3175
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.
3183
3184
3185
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.
3192
3193 ``V4L2_CID_FLASH_STROBE_STOP (button)``
3194     Stop flash strobe immediately.
3195
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.
3199
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.
3203
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)
3207     if possible.
3208
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.
3214
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
3218     possible.
3219
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.
3228
3229 .. tabularcolumns:: |p{8.0cm}|p{9.5cm}|
3230
3231 .. flat-table::
3232     :header-rows:  0
3233     :stub-columns: 0
3234
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
3246         triggered.
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.
3262
3263
3264
3265 ``V4L2_CID_FLASH_CHARGE (boolean)``
3266     Enable or disable charging of the xenon flash capacitor.
3267
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.
3273
3274
3275 .. _jpeg-controls:
3276
3277 JPEG Control Reference
3278 ======================
3279
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
3283 coding.
3284
3285
3286 .. _jpeg-control-id:
3287
3288 JPEG Control IDs
3289 ----------------
3290
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.
3295
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.
3303
3304 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3305
3306 .. flat-table::
3307     :header-rows:  0
3308     :stub-columns: 0
3309
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.
3322
3323
3324
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.
3334
3335 .. _jpeg-quality-control:
3336
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
3345     driver to 0.
3346
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.
3350
3351 .. _jpeg-active-marker-control:
3352
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.
3356
3357
3358
3359 .. flat-table::
3360     :header-rows:  0
3361     :stub-columns: 0
3362
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``
3368       - Comment segment.
3369     * - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
3370       - Quantization tables segment.
3371     * - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
3372       - Huffman tables segment.
3373
3374
3375
3376 For more details about JPEG specification, refer to :ref:`itu-t81`,
3377 :ref:`jfif`, :ref:`w3c-jpeg-jfif`.
3378
3379
3380 .. _image-source-controls:
3381
3382 Image Source Control Reference
3383 ==============================
3384
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.
3389
3390
3391 .. _image-source-control-id:
3392
3393 Image Source Control IDs
3394 ------------------------
3395
3396 ``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
3397     The IMAGE_SOURCE class descriptor.
3398
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
3404     same sub-device.
3405
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
3409     blanking is pixels.
3410
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.
3415
3416 ``V4L2_CID_TEST_PATTERN_RED (integer)``
3417     Test pattern red colour component.
3418
3419 ``V4L2_CID_TEST_PATTERN_GREENR (integer)``
3420     Test pattern green (next to red) colour component.
3421
3422 ``V4L2_CID_TEST_PATTERN_BLUE (integer)``
3423     Test pattern blue colour component.
3424
3425 ``V4L2_CID_TEST_PATTERN_GREENB (integer)``
3426     Test pattern green (next to blue) colour component.
3427
3428
3429 .. _image-process-controls:
3430
3431 Image Process Control Reference
3432 ===============================
3433
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
3437 capturing of it.
3438
3439
3440 .. _image-process-control-id:
3441
3442 Image Process Control IDs
3443 -------------------------
3444
3445 ``V4L2_CID_IMAGE_PROC_CLASS (class)``
3446     The IMAGE_PROC class descriptor.
3447
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.
3462
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.
3466
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.
3471
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`.
3475
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.
3482
3483
3484 .. _dv-controls:
3485
3486 Digital Video Control Reference
3487 ===============================
3488
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.
3496
3497 .. note::
3498
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.
3507
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.
3511
3512
3513 .. _dv-control-id:
3514
3515 Digital Video Control IDs
3516 -------------------------
3517
3518 ``V4L2_CID_DV_CLASS (class)``
3519     The Digital Video class descriptor.
3520
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
3528     connectors.
3529
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
3537     and HDMI devices.
3538
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.
3546
3547 ``V4L2_CID_DV_TX_MODE``
3548     (enum)
3549
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.
3555
3556 ``V4L2_CID_DV_TX_RGB_RANGE``
3557     (enum)
3558
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.
3570
3571 ``V4L2_CID_DV_TX_IT_CONTENT_TYPE``
3572     (enum)
3573
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:
3581
3582 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3583
3584 .. flat-table::
3585     :header-rows:  0
3586     :stub-columns: 0
3587
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``
3596       - Cinema content.
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.
3602
3603
3604
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.
3614
3615 ``V4L2_CID_DV_RX_RGB_RANGE``
3616     (enum)
3617
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.
3629
3630 ``V4L2_CID_DV_RX_IT_CONTENT_TYPE``
3631     (enum)
3632
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.
3640
3641
3642 .. _fm-rx-controls:
3643
3644 FM Receiver Control Reference
3645 =============================
3646
3647 The FM Receiver (FM_RX) class includes controls for common features of
3648 FM Reception capable devices.
3649
3650
3651 .. _fm-rx-control-id:
3652
3653 FM_RX Control IDs
3654 -----------------
3655
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.
3660
3661 ``V4L2_CID_RDS_RECEPTION (boolean)``
3662     Enables/disables RDS reception by the radio tuner
3663
3664 ``V4L2_CID_RDS_RX_PTY (integer)``
3665     Gets RDS Programme Type field. This encodes up to 31 pre-defined
3666     programme types.
3667
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.
3679
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.
3693
3694 ``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
3695     If set, then a traffic announcement is in progress.
3696
3697 ``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
3698     If set, then the tuned programme carries traffic announcements.
3699
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.
3704
3705 ``V4L2_CID_TUNE_DEEMPHASIS``
3706     (enum)
3707
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:
3714
3715
3716
3717 .. flat-table::
3718     :header-rows:  0
3719     :stub-columns: 0
3720
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.
3727
3728
3729
3730
3731 .. _detect-controls:
3732
3733 Detect Control Reference
3734 ========================
3735
3736 The Detect class includes controls for common features of various motion
3737 or object detection capable devices.
3738
3739
3740 .. _detect-control-id:
3741
3742 Detect Control IDs
3743 ------------------
3744
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.
3749
3750 ``V4L2_CID_DETECT_MD_MODE (menu)``
3751     Sets the motion detection mode.
3752
3753 .. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
3754
3755 .. flat-table::
3756     :header-rows:  0
3757     :stub-columns: 0
3758
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.
3774
3775
3776
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.
3780
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.
3786
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.
3792
3793
3794 .. _rf-tuner-controls:
3795
3796 RF Tuner Control Reference
3797 ==========================
3798
3799 The RF Tuner (RF_TUNER) class includes controls for common features of
3800 devices having RF tuner.
3801
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.
3811
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>`__
3815 from Wikipedia.
3816
3817
3818 .. _rf-tuner-control-id:
3819
3820 RF_TUNER Control IDs
3821 --------------------
3822
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.
3827
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.
3831
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.
3838
3839 ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
3840     Enables/disables LNA automatic gain control (AGC)
3841
3842 ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
3843     Enables/disables mixer automatic gain control (AGC)
3844
3845 ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
3846     Enables/disables IF automatic gain control (AGC)
3847
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.
3855
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
3862     driver-specific.
3863
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.
3869
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.
3876
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.
3880
3881 .. [#f1]
3882    This control may be changed to a menu control in the future, if more
3883    options are required.