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/video4linux/cx2341x/README.vbi``)
 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_LEVEL_0``
 946       - Level 0
 947     * - ``V4L2_MPEG_VIDEO_LEVEL_0B``
 948       - Level 0b
 949     * - ``V4L2_MPEG_VIDEO_LEVEL_1``
 950       - Level 1
 951     * - ``V4L2_MPEG_VIDEO_LEVEL_2``
 952       - Level 2
 953     * - ``V4L2_MPEG_VIDEO_LEVEL_3``
 954       - Level 3
 955     * - ``V4L2_MPEG_VIDEO_LEVEL_3B``
 956       - Level 3b
 957     * - ``V4L2_MPEG_VIDEO_LEVEL_4``
 958       - Level 4
 959     * - ``V4L2_MPEG_VIDEO_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_PROFILE_SIMPLE``
1032       - Simple profile
1033     * - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE``
1034       - Advanced Simple profile
1035     * - ``V4L2_MPEG_VIDEO_PROFILE_CORE``
1036       - Core profile
1037     * - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE``
1038       - Simple Scalable profile
1039     * - ``V4L2_MPEG_VIDEO_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     \begin{adjustbox}{width=\columnwidth}
1926
1927 .. tabularcolumns:: |p{11.0cm}|p{10.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     \end{adjustbox}
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_CID_MPEG_VIDEO_VPX_PROFILE (integer)``
1959     Select the desired profile for VPx encoder. Acceptable values are 0,
1960     1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.
1961
1962
1963 .. _camera-controls:
1964
1965 Camera Control Reference
1966 ========================
1967
1968 The Camera class includes controls for mechanical (or equivalent
1969 digital) features of a device such as controllable lenses or sensors.
1970
1971
1972 .. _camera-control-id:
1973
1974 Camera Control IDs
1975 ------------------
1976
1977 ``V4L2_CID_CAMERA_CLASS (class)``
1978     The Camera class descriptor. Calling
1979     :ref:`VIDIOC_QUERYCTRL` for this control will
1980     return a description of this control class.
1981
1982 .. _v4l2-exposure-auto-type:
1983
1984 ``V4L2_CID_EXPOSURE_AUTO``
1985     (enum)
1986
1987 enum v4l2_exposure_auto_type -
1988     Enables automatic adjustments of the exposure time and/or iris
1989     aperture. The effect of manual changes of the exposure time or iris
1990     aperture while these features are enabled is undefined, drivers
1991     should ignore such requests. Possible values are:
1992
1993
1994
1995 .. flat-table::
1996     :header-rows:  0
1997     :stub-columns: 0
1998
1999     * - ``V4L2_EXPOSURE_AUTO``
2000       - Automatic exposure time, automatic iris aperture.
2001     * - ``V4L2_EXPOSURE_MANUAL``
2002       - Manual exposure time, manual iris.
2003     * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
2004       - Manual exposure time, auto iris.
2005     * - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
2006       - Auto exposure time, manual iris.
2007
2008
2009
2010 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
2011     Determines the exposure time of the camera sensor. The exposure time
2012     is limited by the frame interval. Drivers should interpret the
2013     values as 100 µs units, where the value 1 stands for 1/10000th of a
2014     second, 10000 for 1 second and 100000 for 10 seconds.
2015
2016 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
2017     When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
2018     ``APERTURE_PRIORITY``, this control determines if the device may
2019     dynamically vary the frame rate. By default this feature is disabled
2020     (0) and the frame rate must remain constant.
2021
2022 ``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)``
2023     Determines the automatic exposure compensation, it is effective only
2024     when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
2025     ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
2026     terms of EV, drivers should interpret the values as 0.001 EV units,
2027     where the value 1000 stands for +1 EV.
2028
2029     Increasing the exposure compensation value is equivalent to
2030     decreasing the exposure value (EV) and will increase the amount of
2031     light at the image sensor. The camera performs the exposure
2032     compensation by adjusting absolute exposure time and/or aperture.
2033
2034 .. _v4l2-exposure-metering:
2035
2036 ``V4L2_CID_EXPOSURE_METERING``
2037     (enum)
2038
2039 enum v4l2_exposure_metering -
2040     Determines how the camera measures the amount of light available for
2041     the frame exposure. Possible values are:
2042
2043 .. tabularcolumns:: |p{8.5cm}|p{9.0cm}|
2044
2045 .. flat-table::
2046     :header-rows:  0
2047     :stub-columns: 0
2048
2049     * - ``V4L2_EXPOSURE_METERING_AVERAGE``
2050       - Use the light information coming from the entire frame and average
2051         giving no weighting to any particular portion of the metered area.
2052     * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
2053       - Average the light information coming from the entire frame giving
2054         priority to the center of the metered area.
2055     * - ``V4L2_EXPOSURE_METERING_SPOT``
2056       - Measure only very small area at the center of the frame.
2057     * - ``V4L2_EXPOSURE_METERING_MATRIX``
2058       - A multi-zone metering. The light intensity is measured in several
2059         points of the frame and the results are combined. The algorithm of
2060         the zones selection and their significance in calculating the
2061         final value is device dependent.
2062
2063
2064
2065 ``V4L2_CID_PAN_RELATIVE (integer)``
2066     This control turns the camera horizontally by the specified amount.
2067     The unit is undefined. A positive value moves the camera to the
2068     right (clockwise when viewed from above), a negative value to the
2069     left. A value of zero does not cause motion. This is a write-only
2070     control.
2071
2072 ``V4L2_CID_TILT_RELATIVE (integer)``
2073     This control turns the camera vertically by the specified amount.
2074     The unit is undefined. A positive value moves the camera up, a
2075     negative value down. A value of zero does not cause motion. This is
2076     a write-only control.
2077
2078 ``V4L2_CID_PAN_RESET (button)``
2079     When this control is set, the camera moves horizontally to the
2080     default position.
2081
2082 ``V4L2_CID_TILT_RESET (button)``
2083     When this control is set, the camera moves vertically to the default
2084     position.
2085
2086 ``V4L2_CID_PAN_ABSOLUTE (integer)``
2087     This control turns the camera horizontally to the specified
2088     position. Positive values move the camera to the right (clockwise
2089     when viewed from above), negative values to the left. Drivers should
2090     interpret the values as arc seconds, with valid values between -180
2091     * 3600 and +180 * 3600 inclusive.
2092
2093 ``V4L2_CID_TILT_ABSOLUTE (integer)``
2094     This control turns the camera vertically to the specified position.
2095     Positive values move the camera up, negative values down. Drivers
2096     should interpret the values as arc seconds, with valid values
2097     between -180 * 3600 and +180 * 3600 inclusive.
2098
2099 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
2100     This control sets the focal point of the camera to the specified
2101     position. The unit is undefined. Positive values set the focus
2102     closer to the camera, negative values towards infinity.
2103
2104 ``V4L2_CID_FOCUS_RELATIVE (integer)``
2105     This control moves the focal point of the camera by the specified
2106     amount. The unit is undefined. Positive values move the focus closer
2107     to the camera, negative values towards infinity. This is a
2108     write-only control.
2109
2110 ``V4L2_CID_FOCUS_AUTO (boolean)``
2111     Enables continuous automatic focus adjustments. The effect of manual
2112     focus adjustments while this feature is enabled is undefined,
2113     drivers should ignore such requests.
2114
2115 ``V4L2_CID_AUTO_FOCUS_START (button)``
2116     Starts single auto focus process. The effect of setting this control
2117     when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
2118     drivers should ignore such requests.
2119
2120 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
2121     Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
2122     control. It is effective only when the continuous autofocus is
2123     disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
2124     ``FALSE`` (0).
2125
2126 .. _v4l2-auto-focus-status:
2127
2128 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
2129     The automatic focus status. This is a read-only control.
2130
2131     Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
2132     control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
2133     control value.
2134
2135 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
2136
2137 .. flat-table::
2138     :header-rows:  0
2139     :stub-columns: 0
2140
2141     * - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
2142       - Automatic focus is not active.
2143     * - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
2144       - Automatic focusing is in progress.
2145     * - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
2146       - Focus has been reached.
2147     * - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
2148       - Automatic focus has failed, the driver will not transition from
2149         this state until another action is performed by an application.
2150
2151
2152
2153 .. _v4l2-auto-focus-range:
2154
2155 ``V4L2_CID_AUTO_FOCUS_RANGE``
2156     (enum)
2157
2158 enum v4l2_auto_focus_range -
2159     Determines auto focus distance range for which lens may be adjusted.
2160
2161 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
2162
2163 .. flat-table::
2164     :header-rows:  0
2165     :stub-columns: 0
2166
2167     * - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
2168       - The camera automatically selects the focus range.
2169     * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
2170       - Normal distance range, limited for best automatic focus
2171         performance.
2172     * - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
2173       - Macro (close-up) auto focus. The camera will use its minimum
2174         possible distance for auto focus.
2175     * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
2176       - The lens is set to focus on an object at infinite distance.
2177
2178
2179
2180 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
2181     Specify the objective lens focal length as an absolute value. The
2182     zoom unit is driver-specific and its value should be a positive
2183     integer.
2184
2185 ``V4L2_CID_ZOOM_RELATIVE (integer)``
2186     Specify the objective lens focal length relatively to the current
2187     value. Positive values move the zoom lens group towards the
2188     telephoto direction, negative values towards the wide-angle
2189     direction. The zoom unit is driver-specific. This is a write-only
2190     control.
2191
2192 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
2193     Move the objective lens group at the specified speed until it
2194     reaches physical device limits or until an explicit request to stop
2195     the movement. A positive value moves the zoom lens group towards the
2196     telephoto direction. A value of zero stops the zoom lens group
2197     movement. A negative value moves the zoom lens group towards the
2198     wide-angle direction. The zoom speed unit is driver-specific.
2199
2200 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
2201     This control sets the camera's aperture to the specified value. The
2202     unit is undefined. Larger values open the iris wider, smaller values
2203     close it.
2204
2205 ``V4L2_CID_IRIS_RELATIVE (integer)``
2206     This control modifies the camera's aperture by the specified amount.
2207     The unit is undefined. Positive values open the iris one step
2208     further, negative values close it one step further. This is a
2209     write-only control.
2210
2211 ``V4L2_CID_PRIVACY (boolean)``
2212     Prevent video from being acquired by the camera. When this control
2213     is set to ``TRUE`` (1), no image can be captured by the camera.
2214     Common means to enforce privacy are mechanical obturation of the
2215     sensor and firmware image processing, but the device is not
2216     restricted to these methods. Devices that implement the privacy
2217     control must support read access and may support write access.
2218
2219 ``V4L2_CID_BAND_STOP_FILTER (integer)``
2220     Switch the band-stop filter of a camera sensor on or off, or specify
2221     its strength. Such band-stop filters can be used, for example, to
2222     filter out the fluorescent light component.
2223
2224 .. _v4l2-auto-n-preset-white-balance:
2225
2226 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
2227     (enum)
2228
2229 enum v4l2_auto_n_preset_white_balance -
2230     Sets white balance to automatic, manual or a preset. The presets
2231     determine color temperature of the light as a hint to the camera for
2232     white balance adjustments resulting in most accurate color
2233     representation. The following white balance presets are listed in
2234     order of increasing color temperature.
2235
2236 .. tabularcolumns:: |p{7.0 cm}|p{10.5cm}|
2237
2238 .. flat-table::
2239     :header-rows:  0
2240     :stub-columns: 0
2241
2242     * - ``V4L2_WHITE_BALANCE_MANUAL``
2243       - Manual white balance.
2244     * - ``V4L2_WHITE_BALANCE_AUTO``
2245       - Automatic white balance adjustments.
2246     * - ``V4L2_WHITE_BALANCE_INCANDESCENT``
2247       - White balance setting for incandescent (tungsten) lighting. It
2248         generally cools down the colors and corresponds approximately to
2249         2500...3500 K color temperature range.
2250     * - ``V4L2_WHITE_BALANCE_FLUORESCENT``
2251       - White balance preset for fluorescent lighting. It corresponds
2252         approximately to 4000...5000 K color temperature.
2253     * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
2254       - With this setting the camera will compensate for fluorescent H
2255         lighting.
2256     * - ``V4L2_WHITE_BALANCE_HORIZON``
2257       - White balance setting for horizon daylight. It corresponds
2258         approximately to 5000 K color temperature.
2259     * - ``V4L2_WHITE_BALANCE_DAYLIGHT``
2260       - White balance preset for daylight (with clear sky). It corresponds
2261         approximately to 5000...6500 K color temperature.
2262     * - ``V4L2_WHITE_BALANCE_FLASH``
2263       - With this setting the camera will compensate for the flash light.
2264         It slightly warms up the colors and corresponds roughly to
2265         5000...5500 K color temperature.
2266     * - ``V4L2_WHITE_BALANCE_CLOUDY``
2267       - White balance preset for moderately overcast sky. This option
2268         corresponds approximately to 6500...8000 K color temperature
2269         range.
2270     * - ``V4L2_WHITE_BALANCE_SHADE``
2271       - White balance preset for shade or heavily overcast sky. It
2272         corresponds approximately to 9000...10000 K color temperature.
2273
2274
2275
2276 .. _v4l2-wide-dynamic-range:
2277
2278 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
2279     Enables or disables the camera's wide dynamic range feature. This
2280     feature allows to obtain clear images in situations where intensity
2281     of the illumination varies significantly throughout the scene, i.e.
2282     there are simultaneously very dark and very bright areas. It is most
2283     commonly realized in cameras by combining two subsequent frames with
2284     different exposure times.  [#f1]_
2285
2286 .. _v4l2-image-stabilization:
2287
2288 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
2289     Enables or disables image stabilization.
2290
2291 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
2292     Determines ISO equivalent of an image sensor indicating the sensor's
2293     sensitivity to light. The numbers are expressed in arithmetic scale,
2294     as per :ref:`iso12232` standard, where doubling the sensor
2295     sensitivity is represented by doubling the numerical ISO value.
2296     Applications should interpret the values as standard ISO values
2297     multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
2298     Drivers will usually support only a subset of standard ISO values.
2299     The effect of setting this control while the
2300     ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
2301     than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
2302     should ignore such requests.
2303
2304 .. _v4l2-iso-sensitivity-auto-type:
2305
2306 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
2307     (enum)
2308
2309 enum v4l2_iso_sensitivity_type -
2310     Enables or disables automatic ISO sensitivity adjustments.
2311
2312
2313
2314 .. flat-table::
2315     :header-rows:  0
2316     :stub-columns: 0
2317
2318     * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
2319       - Manual ISO sensitivity.
2320     * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
2321       - Automatic ISO sensitivity adjustments.
2322
2323
2324
2325 .. _v4l2-scene-mode:
2326
2327 ``V4L2_CID_SCENE_MODE``
2328     (enum)
2329
2330 enum v4l2_scene_mode -
2331     This control allows to select scene programs as the camera automatic
2332     modes optimized for common shooting scenes. Within these modes the
2333     camera determines best exposure, aperture, focusing, light metering,
2334     white balance and equivalent sensitivity. The controls of those
2335     parameters are influenced by the scene mode control. An exact
2336     behavior in each mode is subject to the camera specification.
2337
2338     When the scene mode feature is not used, this control should be set
2339     to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
2340     controls are accessible. The following scene programs are defined:
2341
2342 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
2343
2344 .. flat-table::
2345     :header-rows:  0
2346     :stub-columns: 0
2347
2348     * - ``V4L2_SCENE_MODE_NONE``
2349       - The scene mode feature is disabled.
2350     * - ``V4L2_SCENE_MODE_BACKLIGHT``
2351       - Backlight. Compensates for dark shadows when light is coming from
2352         behind a subject, also by automatically turning on the flash.
2353     * - ``V4L2_SCENE_MODE_BEACH_SNOW``
2354       - Beach and snow. This mode compensates for all-white or bright
2355         scenes, which tend to look gray and low contrast, when camera's
2356         automatic exposure is based on an average scene brightness. To
2357         compensate, this mode automatically slightly overexposes the
2358         frames. The white balance may also be adjusted to compensate for
2359         the fact that reflected snow looks bluish rather than white.
2360     * - ``V4L2_SCENE_MODE_CANDLELIGHT``
2361       - Candle light. The camera generally raises the ISO sensitivity and
2362         lowers the shutter speed. This mode compensates for relatively
2363         close subject in the scene. The flash is disabled in order to
2364         preserve the ambiance of the light.
2365     * - ``V4L2_SCENE_MODE_DAWN_DUSK``
2366       - Dawn and dusk. Preserves the colors seen in low natural light
2367         before dusk and after down. The camera may turn off the flash, and
2368         automatically focus at infinity. It will usually boost saturation
2369         and lower the shutter speed.
2370     * - ``V4L2_SCENE_MODE_FALL_COLORS``
2371       - Fall colors. Increases saturation and adjusts white balance for
2372         color enhancement. Pictures of autumn leaves get saturated reds
2373         and yellows.
2374     * - ``V4L2_SCENE_MODE_FIREWORKS``
2375       - Fireworks. Long exposure times are used to capture the expanding
2376         burst of light from a firework. The camera may invoke image
2377         stabilization.
2378     * - ``V4L2_SCENE_MODE_LANDSCAPE``
2379       - Landscape. The camera may choose a small aperture to provide deep
2380         depth of field and long exposure duration to help capture detail
2381         in dim light conditions. The focus is fixed at infinity. Suitable
2382         for distant and wide scenery.
2383     * - ``V4L2_SCENE_MODE_NIGHT``
2384       - Night, also known as Night Landscape. Designed for low light
2385         conditions, it preserves detail in the dark areas without blowing
2386         out bright objects. The camera generally sets itself to a
2387         medium-to-high ISO sensitivity, with a relatively long exposure
2388         time, and turns flash off. As such, there will be increased image
2389         noise and the possibility of blurred image.
2390     * - ``V4L2_SCENE_MODE_PARTY_INDOOR``
2391       - Party and indoor. Designed to capture indoor scenes that are lit
2392         by indoor background lighting as well as the flash. The camera
2393         usually increases ISO sensitivity, and adjusts exposure for the
2394         low light conditions.
2395     * - ``V4L2_SCENE_MODE_PORTRAIT``
2396       - Portrait. The camera adjusts the aperture so that the depth of
2397         field is reduced, which helps to isolate the subject against a
2398         smooth background. Most cameras recognize the presence of faces in
2399         the scene and focus on them. The color hue is adjusted to enhance
2400         skin tones. The intensity of the flash is often reduced.
2401     * - ``V4L2_SCENE_MODE_SPORTS``
2402       - Sports. Significantly increases ISO and uses a fast shutter speed
2403         to freeze motion of rapidly-moving subjects. Increased image noise
2404         may be seen in this mode.
2405     * - ``V4L2_SCENE_MODE_SUNSET``
2406       - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
2407         up the saturation.
2408     * - ``V4L2_SCENE_MODE_TEXT``
2409       - Text. It applies extra contrast and sharpness, it is typically a
2410         black-and-white mode optimized for readability. Automatic focus
2411         may be switched to close-up mode and this setting may also involve
2412         some lens-distortion correction.
2413
2414
2415
2416 ``V4L2_CID_3A_LOCK (bitmask)``
2417     This control locks or unlocks the automatic focus, exposure and
2418     white balance. The automatic adjustments can be paused independently
2419     by setting the corresponding lock bit to 1. The camera then retains
2420     the settings until the lock bit is cleared. The following lock bits
2421     are defined:
2422
2423     When a given algorithm is not enabled, drivers should ignore
2424     requests to lock it and should return no error. An example might be
2425     an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
2426     ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
2427     value of this control may be changed by exposure, white balance or
2428     focus controls.
2429
2430
2431
2432 .. flat-table::
2433     :header-rows:  0
2434     :stub-columns: 0
2435
2436     * - ``V4L2_LOCK_EXPOSURE``
2437       - Automatic exposure adjustments lock.
2438     * - ``V4L2_LOCK_WHITE_BALANCE``
2439       - Automatic white balance adjustments lock.
2440     * - ``V4L2_LOCK_FOCUS``
2441       - Automatic focus lock.
2442
2443
2444
2445 ``V4L2_CID_PAN_SPEED (integer)``
2446     This control turns the camera horizontally at the specific speed.
2447     The unit is undefined. A positive value moves the camera to the
2448     right (clockwise when viewed from above), a negative value to the
2449     left. A value of zero stops the motion if one is in progress and has
2450     no effect otherwise.
2451
2452 ``V4L2_CID_TILT_SPEED (integer)``
2453     This control turns the camera vertically at the specified speed. The
2454     unit is undefined. A positive value moves the camera up, a negative
2455     value down. A value of zero stops the motion if one is in progress
2456     and has no effect otherwise.
2457
2458
2459 .. _fm-tx-controls:
2460
2461 FM Transmitter Control Reference
2462 ================================
2463
2464 The FM Transmitter (FM_TX) class includes controls for common features
2465 of FM transmissions capable devices. Currently this class includes
2466 parameters for audio compression, pilot tone generation, audio deviation
2467 limiter, RDS transmission and tuning power features.
2468
2469
2470 .. _fm-tx-control-id:
2471
2472 FM_TX Control IDs
2473 -----------------
2474
2475 ``V4L2_CID_FM_TX_CLASS (class)``
2476     The FM_TX class descriptor. Calling
2477     :ref:`VIDIOC_QUERYCTRL` for this control will
2478     return a description of this control class.
2479
2480 ``V4L2_CID_RDS_TX_DEVIATION (integer)``
2481     Configures RDS signal frequency deviation level in Hz. The range and
2482     step are driver-specific.
2483
2484 ``V4L2_CID_RDS_TX_PI (integer)``
2485     Sets the RDS Programme Identification field for transmission.
2486
2487 ``V4L2_CID_RDS_TX_PTY (integer)``
2488     Sets the RDS Programme Type field for transmission. This encodes up
2489     to 31 pre-defined programme types.
2490
2491 ``V4L2_CID_RDS_TX_PS_NAME (string)``
2492     Sets the Programme Service name (PS_NAME) for transmission. It is
2493     intended for static display on a receiver. It is the primary aid to
2494     listeners in programme service identification and selection. In
2495     Annex E of :ref:`iec62106`, the RDS specification, there is a full
2496     description of the correct character encoding for Programme Service
2497     name strings. Also from RDS specification, PS is usually a single
2498     eight character text. However, it is also possible to find receivers
2499     which can scroll strings sized as 8 x N characters. So, this control
2500     must be configured with steps of 8 characters. The result is it must
2501     always contain a string with size multiple of 8.
2502
2503 ``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
2504     Sets the Radio Text info for transmission. It is a textual
2505     description of what is being broadcasted. RDS Radio Text can be
2506     applied when broadcaster wishes to transmit longer PS names,
2507     programme-related information or any other text. In these cases,
2508     RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
2509     The encoding for Radio Text strings is also fully described in Annex
2510     E of :ref:`iec62106`. The length of Radio Text strings depends on
2511     which RDS Block is being used to transmit it, either 32 (2A block)
2512     or 64 (2B block). However, it is also possible to find receivers
2513     which can scroll strings sized as 32 x N or 64 x N characters. So,
2514     this control must be configured with steps of 32 or 64 characters.
2515     The result is it must always contain a string with size multiple of
2516     32 or 64.
2517
2518 ``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
2519     Sets the Mono/Stereo bit of the Decoder Identification code. If set,
2520     then the audio was recorded as stereo.
2521
2522 ``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
2523     Sets the
2524     `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
2525     bit of the Decoder Identification code. If set, then the audio was
2526     recorded using an artificial head.
2527
2528 ``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
2529     Sets the Compressed bit of the Decoder Identification code. If set,
2530     then the audio is compressed.
2531
2532 ``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
2533     Sets the Dynamic PTY bit of the Decoder Identification code. If set,
2534     then the PTY code is dynamically switched.
2535
2536 ``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
2537     If set, then a traffic announcement is in progress.
2538
2539 ``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
2540     If set, then the tuned programme carries traffic announcements.
2541
2542 ``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
2543     If set, then this channel broadcasts music. If cleared, then it
2544     broadcasts speech. If the transmitter doesn't make this distinction,
2545     then it should be set.
2546
2547 ``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
2548     If set, then transmit alternate frequencies.
2549
2550 ``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
2551     The alternate frequencies in kHz units. The RDS standard allows for
2552     up to 25 frequencies to be defined. Drivers may support fewer
2553     frequencies so check the array size.
2554
2555 ``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
2556     Enables or disables the audio deviation limiter feature. The limiter
2557     is useful when trying to maximize the audio volume, minimize
2558     receiver-generated distortion and prevent overmodulation.
2559
2560 ``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
2561     Sets the audio deviation limiter feature release time. Unit is in
2562     useconds. Step and range are driver-specific.
2563
2564 ``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
2565     Configures audio frequency deviation level in Hz. The range and step
2566     are driver-specific.
2567
2568 ``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
2569     Enables or disables the audio compression feature. This feature
2570     amplifies signals below the threshold by a fixed gain and compresses
2571     audio signals above the threshold by the ratio of Threshold/(Gain +
2572     Threshold).
2573
2574 ``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
2575     Sets the gain for audio compression feature. It is a dB value. The
2576     range and step are driver-specific.
2577
2578 ``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
2579     Sets the threshold level for audio compression freature. It is a dB
2580     value. The range and step are driver-specific.
2581
2582 ``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
2583     Sets the attack time for audio compression feature. It is a useconds
2584     value. The range and step are driver-specific.
2585
2586 ``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
2587     Sets the release time for audio compression feature. It is a
2588     useconds value. The range and step are driver-specific.
2589
2590 ``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
2591     Enables or disables the pilot tone generation feature.
2592
2593 ``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
2594     Configures pilot tone frequency deviation level. Unit is in Hz. The
2595     range and step are driver-specific.
2596
2597 ``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
2598     Configures pilot tone frequency value. Unit is in Hz. The range and
2599     step are driver-specific.
2600
2601 ``V4L2_CID_TUNE_PREEMPHASIS``
2602     (enum)
2603
2604 enum v4l2_preemphasis -
2605     Configures the pre-emphasis value for broadcasting. A pre-emphasis
2606     filter is applied to the broadcast to accentuate the high audio
2607     frequencies. Depending on the region, a time constant of either 50
2608     or 75 useconds is used. The enum v4l2_preemphasis defines possible
2609     values for pre-emphasis. Here they are:
2610
2611
2612
2613 .. flat-table::
2614     :header-rows:  0
2615     :stub-columns: 0
2616
2617     * - ``V4L2_PREEMPHASIS_DISABLED``
2618       - No pre-emphasis is applied.
2619     * - ``V4L2_PREEMPHASIS_50_uS``
2620       - A pre-emphasis of 50 uS is used.
2621     * - ``V4L2_PREEMPHASIS_75_uS``
2622       - A pre-emphasis of 75 uS is used.
2623
2624
2625
2626 ``V4L2_CID_TUNE_POWER_LEVEL (integer)``
2627     Sets the output power level for signal transmission. Unit is in
2628     dBuV. Range and step are driver-specific.
2629
2630 ``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
2631     This selects the value of antenna tuning capacitor manually or
2632     automatically if set to zero. Unit, range and step are
2633     driver-specific.
2634
2635 For more details about RDS specification, refer to :ref:`iec62106`
2636 document, from CENELEC.
2637
2638
2639 .. _flash-controls:
2640
2641 Flash Control Reference
2642 =======================
2643
2644 The V4L2 flash controls are intended to provide generic access to flash
2645 controller devices. Flash controller devices are typically used in
2646 digital cameras.
2647
2648 The interface can support both LED and xenon flash devices. As of
2649 writing this, there is no xenon flash driver using this interface.
2650
2651
2652 .. _flash-controls-use-cases:
2653
2654 Supported use cases
2655 -------------------
2656
2657
2658 Unsynchronised LED flash (software strobe)
2659 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2660
2661 Unsynchronised LED flash is controlled directly by the host as the
2662 sensor. The flash must be enabled by the host before the exposure of the
2663 image starts and disabled once it ends. The host is fully responsible
2664 for the timing of the flash.
2665
2666 Example of such device: Nokia N900.
2667
2668
2669 Synchronised LED flash (hardware strobe)
2670 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2671
2672 The synchronised LED flash is pre-programmed by the host (power and
2673 timeout) but controlled by the sensor through a strobe signal from the
2674 sensor to the flash.
2675
2676 The sensor controls the flash duration and timing. This information
2677 typically must be made available to the sensor.
2678
2679
2680 LED flash as torch
2681 ^^^^^^^^^^^^^^^^^^
2682
2683 LED flash may be used as torch in conjunction with another use case
2684 involving camera or individually.
2685
2686
2687 .. _flash-control-id:
2688
2689 Flash Control IDs
2690 """""""""""""""""
2691
2692 ``V4L2_CID_FLASH_CLASS (class)``
2693     The FLASH class descriptor.
2694
2695 ``V4L2_CID_FLASH_LED_MODE (menu)``
2696     Defines the mode of the flash LED, the high-power white LED attached
2697     to the flash controller. Setting this control may not be possible in
2698     presence of some faults. See V4L2_CID_FLASH_FAULT.
2699
2700
2701
2702 .. flat-table::
2703     :header-rows:  0
2704     :stub-columns: 0
2705
2706     * - ``V4L2_FLASH_LED_MODE_NONE``
2707       - Off.
2708     * - ``V4L2_FLASH_LED_MODE_FLASH``
2709       - Flash mode.
2710     * - ``V4L2_FLASH_LED_MODE_TORCH``
2711       - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
2712
2713
2714
2715 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
2716     Defines the source of the flash LED strobe.
2717
2718 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
2719
2720 .. flat-table::
2721     :header-rows:  0
2722     :stub-columns: 0
2723
2724     * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
2725       - The flash strobe is triggered by using the
2726         V4L2_CID_FLASH_STROBE control.
2727     * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
2728       - The flash strobe is triggered by an external source. Typically
2729         this is a sensor, which makes it possible to synchronises the
2730         flash strobe start to exposure start.
2731
2732
2733
2734 ``V4L2_CID_FLASH_STROBE (button)``
2735     Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
2736     V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
2737     is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
2738     control may not be possible in presence of some faults. See
2739     V4L2_CID_FLASH_FAULT.
2740
2741 ``V4L2_CID_FLASH_STROBE_STOP (button)``
2742     Stop flash strobe immediately.
2743
2744 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
2745     Strobe status: whether the flash is strobing at the moment or not.
2746     This is a read-only control.
2747
2748 ``V4L2_CID_FLASH_TIMEOUT (integer)``
2749     Hardware timeout for flash. The flash strobe is stopped after this
2750     period of time has passed from the start of the strobe.
2751
2752 ``V4L2_CID_FLASH_INTENSITY (integer)``
2753     Intensity of the flash strobe when the flash LED is in flash mode
2754     (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
2755     if possible.
2756
2757 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
2758     Intensity of the flash LED in torch mode
2759     (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
2760     if possible. Setting this control may not be possible in presence of
2761     some faults. See V4L2_CID_FLASH_FAULT.
2762
2763 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
2764     Intensity of the indicator LED. The indicator LED may be fully
2765     independent of the flash LED. The unit should be microamps (uA) if
2766     possible.
2767
2768 ``V4L2_CID_FLASH_FAULT (bitmask)``
2769     Faults related to the flash. The faults tell about specific problems
2770     in the flash chip itself or the LEDs attached to it. Faults may
2771     prevent further use of some of the flash controls. In particular,
2772     V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
2773     if the fault affects the flash LED. Exactly which faults have such
2774     an effect is chip dependent. Reading the faults resets the control
2775     and returns the chip to a usable state if possible.
2776
2777 .. tabularcolumns:: |p{8.0cm}|p{9.5cm}|
2778
2779 .. flat-table::
2780     :header-rows:  0
2781     :stub-columns: 0
2782
2783     * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
2784       - Flash controller voltage to the flash LED has exceeded the limit
2785         specific to the flash controller.
2786     * - ``V4L2_FLASH_FAULT_TIMEOUT``
2787       - The flash strobe was still on when the timeout set by the user ---
2788         V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
2789         controllers may set this in all such conditions.
2790     * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
2791       - The flash controller has overheated.
2792     * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
2793       - The short circuit protection of the flash controller has been
2794         triggered.
2795     * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
2796       - Current in the LED power supply has exceeded the limit specific to
2797         the flash controller.
2798     * - ``V4L2_FLASH_FAULT_INDICATOR``
2799       - The flash controller has detected a short or open circuit
2800         condition on the indicator LED.
2801     * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
2802       - Flash controller voltage to the flash LED has been below the
2803         minimum limit specific to the flash controller.
2804     * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
2805       - The input voltage of the flash controller is below the limit under
2806         which strobing the flash at full current will not be possible.The
2807         condition persists until this flag is no longer set.
2808     * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
2809       - The temperature of the LED has exceeded its allowed upper limit.
2810
2811
2812
2813 ``V4L2_CID_FLASH_CHARGE (boolean)``
2814     Enable or disable charging of the xenon flash capacitor.
2815
2816 ``V4L2_CID_FLASH_READY (boolean)``
2817     Is the flash ready to strobe? Xenon flashes require their capacitors
2818     charged before strobing. LED flashes often require a cooldown period
2819     after strobe during which another strobe will not be possible. This
2820     is a read-only control.
2821
2822
2823 .. _jpeg-controls:
2824
2825 JPEG Control Reference
2826 ======================
2827
2828 The JPEG class includes controls for common features of JPEG encoders
2829 and decoders. Currently it includes features for codecs implementing
2830 progressive baseline DCT compression process with Huffman entrophy
2831 coding.
2832
2833
2834 .. _jpeg-control-id:
2835
2836 JPEG Control IDs
2837 ----------------
2838
2839 ``V4L2_CID_JPEG_CLASS (class)``
2840     The JPEG class descriptor. Calling
2841     :ref:`VIDIOC_QUERYCTRL` for this control will
2842     return a description of this control class.
2843
2844 ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
2845     The chroma subsampling factors describe how each component of an
2846     input image is sampled, in respect to maximum sample rate in each
2847     spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
2848     details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
2849     how Cb and Cr components are downsampled after converting an input
2850     image from RGB to Y'CbCr color space.
2851
2852 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
2853
2854 .. flat-table::
2855     :header-rows:  0
2856     :stub-columns: 0
2857
2858     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
2859       - No chroma subsampling, each pixel has Y, Cr and Cb values.
2860     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
2861       - Horizontally subsample Cr, Cb components by a factor of 2.
2862     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
2863       - Subsample Cr, Cb components horizontally and vertically by 2.
2864     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
2865       - Horizontally subsample Cr, Cb components by a factor of 4.
2866     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
2867       - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
2868     * - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
2869       - Use only luminance component.
2870
2871
2872
2873 ``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
2874     The restart interval determines an interval of inserting RSTm
2875     markers (m = 0..7). The purpose of these markers is to additionally
2876     reinitialize the encoder process, in order to process blocks of an
2877     image independently. For the lossy compression processes the restart
2878     interval unit is MCU (Minimum Coded Unit) and its value is contained
2879     in DRI (Define Restart Interval) marker. If
2880     ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
2881     markers will not be inserted.
2882
2883 .. _jpeg-quality-control:
2884
2885 ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
2886     ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
2887     between image quality and size. It provides simpler method for
2888     applications to control image quality, without a need for direct
2889     reconfiguration of luminance and chrominance quantization tables. In
2890     cases where a driver uses quantization tables configured directly by
2891     an application, using interfaces defined elsewhere,
2892     ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
2893     driver to 0.
2894
2895     The value range of this control is driver-specific. Only positive,
2896     non-zero values are meaningful. The recommended range is 1 - 100,
2897     where larger values correspond to better image quality.
2898
2899 .. _jpeg-active-marker-control:
2900
2901 ``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
2902     Specify which JPEG markers are included in compressed stream. This
2903     control is valid only for encoders.
2904
2905
2906
2907 .. flat-table::
2908     :header-rows:  0
2909     :stub-columns: 0
2910
2911     * - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
2912       - Application data segment APP\ :sub:`0`.
2913     * - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
2914       - Application data segment APP\ :sub:`1`.
2915     * - ``V4L2_JPEG_ACTIVE_MARKER_COM``
2916       - Comment segment.
2917     * - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
2918       - Quantization tables segment.
2919     * - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
2920       - Huffman tables segment.
2921
2922
2923
2924 For more details about JPEG specification, refer to :ref:`itu-t81`,
2925 :ref:`jfif`, :ref:`w3c-jpeg-jfif`.
2926
2927
2928 .. _image-source-controls:
2929
2930 Image Source Control Reference
2931 ==============================
2932
2933 The Image Source control class is intended for low-level control of
2934 image source devices such as image sensors. The devices feature an
2935 analogue to digital converter and a bus transmitter to transmit the
2936 image data out of the device.
2937
2938
2939 .. _image-source-control-id:
2940
2941 Image Source Control IDs
2942 ------------------------
2943
2944 ``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
2945     The IMAGE_SOURCE class descriptor.
2946
2947 ``V4L2_CID_VBLANK (integer)``
2948     Vertical blanking. The idle period after every frame during which no
2949     image data is produced. The unit of vertical blanking is a line.
2950     Every line has length of the image width plus horizontal blanking at
2951     the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
2952     same sub-device.
2953
2954 ``V4L2_CID_HBLANK (integer)``
2955     Horizontal blanking. The idle period after every line of image data
2956     during which no image data is produced. The unit of horizontal
2957     blanking is pixels.
2958
2959 ``V4L2_CID_ANALOGUE_GAIN (integer)``
2960     Analogue gain is gain affecting all colour components in the pixel
2961     matrix. The gain operation is performed in the analogue domain
2962     before A/D conversion.
2963
2964 ``V4L2_CID_TEST_PATTERN_RED (integer)``
2965     Test pattern red colour component.
2966
2967 ``V4L2_CID_TEST_PATTERN_GREENR (integer)``
2968     Test pattern green (next to red) colour component.
2969
2970 ``V4L2_CID_TEST_PATTERN_BLUE (integer)``
2971     Test pattern blue colour component.
2972
2973 ``V4L2_CID_TEST_PATTERN_GREENB (integer)``
2974     Test pattern green (next to blue) colour component.
2975
2976
2977 .. _image-process-controls:
2978
2979 Image Process Control Reference
2980 ===============================
2981
2982 The Image Process control class is intended for low-level control of
2983 image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
2984 controls in this class affect processing the image, and do not control
2985 capturing of it.
2986
2987
2988 .. _image-process-control-id:
2989
2990 Image Process Control IDs
2991 -------------------------
2992
2993 ``V4L2_CID_IMAGE_PROC_CLASS (class)``
2994     The IMAGE_PROC class descriptor.
2995
2996 ``V4L2_CID_LINK_FREQ (integer menu)``
2997     Data bus frequency. Together with the media bus pixel code, bus type
2998     (clock cycles per sample), the data bus frequency defines the pixel
2999     rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly
3000     elsewhere, if the device is not an image sensor). The frame rate can
3001     be calculated from the pixel clock, image width and height and
3002     horizontal and vertical blanking. While the pixel rate control may
3003     be defined elsewhere than in the subdev containing the pixel array,
3004     the frame rate cannot be obtained from that information. This is
3005     because only on the pixel array it can be assumed that the vertical
3006     and horizontal blanking information is exact: no other blanking is
3007     allowed in the pixel array. The selection of frame rate is performed
3008     by selecting the desired horizontal and vertical blanking. The unit
3009     of this control is Hz.
3010
3011 ``V4L2_CID_PIXEL_RATE (64-bit integer)``
3012     Pixel rate in the source pads of the subdev. This control is
3013     read-only and its unit is pixels / second.
3014
3015 ``V4L2_CID_TEST_PATTERN (menu)``
3016     Some capture/display/sensor devices have the capability to generate
3017     test pattern images. These hardware specific test patterns can be
3018     used to test if a device is working properly.
3019
3020 ``V4L2_CID_DEINTERLACING_MODE (menu)``
3021     The video deinterlacing mode (such as Bob, Weave, ...). The menu items are
3022     driver specific and are documented in :ref:`v4l-drivers`.
3023
3024 ``V4L2_CID_DIGITAL_GAIN (integer)``
3025     Digital gain is the value by which all colour components
3026     are multiplied by. Typically the digital gain applied is the
3027     control value divided by e.g. 0x100, meaning that to get no
3028     digital gain the control value needs to be 0x100. The no-gain
3029     configuration is also typically the default.
3030
3031
3032 .. _dv-controls:
3033
3034 Digital Video Control Reference
3035 ===============================
3036
3037 The Digital Video control class is intended to control receivers and
3038 transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
3039 `DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
3040 (Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
3041 (:ref:`dp`). These controls are generally expected to be private to
3042 the receiver or transmitter subdevice that implements them, so they are
3043 only exposed on the ``/dev/v4l-subdev*`` device node.
3044
3045 .. note::
3046
3047    Note that these devices can have multiple input or output pads which are
3048    hooked up to e.g. HDMI connectors. Even though the subdevice will
3049    receive or transmit video from/to only one of those pads, the other pads
3050    can still be active when it comes to EDID (Extended Display
3051    Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
3052    Content Protection System, :ref:`hdcp`) processing, allowing the
3053    device to do the fairly slow EDID/HDCP handling in advance. This allows
3054    for quick switching between connectors.
3055
3056 These pads appear in several of the controls in this section as
3057 bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
3058 1, etc. The maximum value of the control is the set of valid pads.
3059
3060
3061 .. _dv-control-id:
3062
3063 Digital Video Control IDs
3064 -------------------------
3065
3066 ``V4L2_CID_DV_CLASS (class)``
3067     The Digital Video class descriptor.
3068
3069 ``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
3070     Many connectors have a hotplug pin which is high if EDID information
3071     is available from the source. This control shows the state of the
3072     hotplug pin as seen by the transmitter. Each bit corresponds to an
3073     output pad on the transmitter. If an output pad does not have an
3074     associated hotplug pin, then the bit for that pad will be 0. This
3075     read-only control is applicable to DVI-D, HDMI and DisplayPort
3076     connectors.
3077
3078 ``V4L2_CID_DV_TX_RXSENSE (bitmask)``
3079     Rx Sense is the detection of pull-ups on the TMDS clock lines. This
3080     normally means that the sink has left/entered standby (i.e. the
3081     transmitter can sense that the receiver is ready to receive video).
3082     Each bit corresponds to an output pad on the transmitter. If an
3083     output pad does not have an associated Rx Sense, then the bit for
3084     that pad will be 0. This read-only control is applicable to DVI-D
3085     and HDMI devices.
3086
3087 ``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
3088     When the transmitter sees the hotplug signal from the receiver it
3089     will attempt to read the EDID. If set, then the transmitter has read
3090     at least the first block (= 128 bytes). Each bit corresponds to an
3091     output pad on the transmitter. If an output pad does not support
3092     EDIDs, then the bit for that pad will be 0. This read-only control
3093     is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
3094
3095 ``V4L2_CID_DV_TX_MODE``
3096     (enum)
3097
3098 enum v4l2_dv_tx_mode -
3099     HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
3100     mode (video + audio + auxiliary data). This control selects which
3101     mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
3102     This control is applicable to HDMI connectors.
3103
3104 ``V4L2_CID_DV_TX_RGB_RANGE``
3105     (enum)
3106
3107 enum v4l2_dv_rgb_range -
3108     Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
3109     follows the RGB quantization range specified in the standard for the
3110     video interface (ie. :ref:`cea861` for HDMI).
3111     V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
3112     standard to be compatible with sinks that have not implemented the
3113     standard correctly (unfortunately quite common for HDMI and DVI-D).
3114     Full range allows all possible values to be used whereas limited
3115     range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
3116     the number of bits per component. This control is applicable to VGA,
3117     DVI-A/D, HDMI and DisplayPort connectors.
3118
3119 ``V4L2_CID_DV_TX_IT_CONTENT_TYPE``
3120     (enum)
3121
3122 enum v4l2_dv_it_content_type -
3123     Configures the IT Content Type of the transmitted video. This
3124     information is sent over HDMI and DisplayPort connectors as part of
3125     the AVI InfoFrame. The term 'IT Content' is used for content that
3126     originates from a computer as opposed to content from a TV broadcast
3127     or an analog source. The enum v4l2_dv_it_content_type defines
3128     the possible content types:
3129
3130 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3131
3132 .. flat-table::
3133     :header-rows:  0
3134     :stub-columns: 0
3135
3136     * - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
3137       - Graphics content. Pixel data should be passed unfiltered and
3138         without analog reconstruction.
3139     * - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
3140       - Photo content. The content is derived from digital still pictures.
3141         The content should be passed through with minimal scaling and
3142         picture enhancements.
3143     * - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
3144       - Cinema content.
3145     * - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
3146       - Game content. Audio and video latency should be minimized.
3147     * - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
3148       - No IT Content information is available and the ITC bit in the AVI
3149         InfoFrame is set to 0.
3150
3151
3152
3153 ``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
3154     Detects whether the receiver receives power from the source (e.g.
3155     HDMI carries 5V on one of the pins). This is often used to power an
3156     eeprom which contains EDID information, such that the source can
3157     read the EDID even if the sink is in standby/power off. Each bit
3158     corresponds to an input pad on the transmitter. If an input pad
3159     cannot detect whether power is present, then the bit for that pad
3160     will be 0. This read-only control is applicable to DVI-D, HDMI and
3161     DisplayPort connectors.
3162
3163 ``V4L2_CID_DV_RX_RGB_RANGE``
3164     (enum)
3165
3166 enum v4l2_dv_rgb_range -
3167     Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
3168     follows the RGB quantization range specified in the standard for the
3169     video interface (ie. :ref:`cea861` for HDMI).
3170     V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
3171     standard to be compatible with sources that have not implemented the
3172     standard correctly (unfortunately quite common for HDMI and DVI-D).
3173     Full range allows all possible values to be used whereas limited
3174     range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
3175     the number of bits per component. This control is applicable to VGA,
3176     DVI-A/D, HDMI and DisplayPort connectors.
3177
3178 ``V4L2_CID_DV_RX_IT_CONTENT_TYPE``
3179     (enum)
3180
3181 enum v4l2_dv_it_content_type -
3182     Reads the IT Content Type of the received video. This information is
3183     sent over HDMI and DisplayPort connectors as part of the AVI
3184     InfoFrame. The term 'IT Content' is used for content that originates
3185     from a computer as opposed to content from a TV broadcast or an
3186     analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
3187     available content types.
3188
3189
3190 .. _fm-rx-controls:
3191
3192 FM Receiver Control Reference
3193 =============================
3194
3195 The FM Receiver (FM_RX) class includes controls for common features of
3196 FM Reception capable devices.
3197
3198
3199 .. _fm-rx-control-id:
3200
3201 FM_RX Control IDs
3202 -----------------
3203
3204 ``V4L2_CID_FM_RX_CLASS (class)``
3205     The FM_RX class descriptor. Calling
3206     :ref:`VIDIOC_QUERYCTRL` for this control will
3207     return a description of this control class.
3208
3209 ``V4L2_CID_RDS_RECEPTION (boolean)``
3210     Enables/disables RDS reception by the radio tuner
3211
3212 ``V4L2_CID_RDS_RX_PTY (integer)``
3213     Gets RDS Programme Type field. This encodes up to 31 pre-defined
3214     programme types.
3215
3216 ``V4L2_CID_RDS_RX_PS_NAME (string)``
3217     Gets the Programme Service name (PS_NAME). It is intended for
3218     static display on a receiver. It is the primary aid to listeners in
3219     programme service identification and selection. In Annex E of
3220     :ref:`iec62106`, the RDS specification, there is a full
3221     description of the correct character encoding for Programme Service
3222     name strings. Also from RDS specification, PS is usually a single
3223     eight character text. However, it is also possible to find receivers
3224     which can scroll strings sized as 8 x N characters. So, this control
3225     must be configured with steps of 8 characters. The result is it must
3226     always contain a string with size multiple of 8.
3227
3228 ``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
3229     Gets the Radio Text info. It is a textual description of what is
3230     being broadcasted. RDS Radio Text can be applied when broadcaster
3231     wishes to transmit longer PS names, programme-related information or
3232     any other text. In these cases, RadioText can be used in addition to
3233     ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
3234     also fully described in Annex E of :ref:`iec62106`. The length of
3235     Radio Text strings depends on which RDS Block is being used to
3236     transmit it, either 32 (2A block) or 64 (2B block). However, it is
3237     also possible to find receivers which can scroll strings sized as 32
3238     x N or 64 x N characters. So, this control must be configured with
3239     steps of 32 or 64 characters. The result is it must always contain a
3240     string with size multiple of 32 or 64.
3241
3242 ``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
3243     If set, then a traffic announcement is in progress.
3244
3245 ``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
3246     If set, then the tuned programme carries traffic announcements.
3247
3248 ``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
3249     If set, then this channel broadcasts music. If cleared, then it
3250     broadcasts speech. If the transmitter doesn't make this distinction,
3251     then it will be set.
3252
3253 ``V4L2_CID_TUNE_DEEMPHASIS``
3254     (enum)
3255
3256 enum v4l2_deemphasis -
3257     Configures the de-emphasis value for reception. A de-emphasis filter
3258     is applied to the broadcast to accentuate the high audio
3259     frequencies. Depending on the region, a time constant of either 50
3260     or 75 useconds is used. The enum v4l2_deemphasis defines possible
3261     values for de-emphasis. Here they are:
3262
3263
3264
3265 .. flat-table::
3266     :header-rows:  0
3267     :stub-columns: 0
3268
3269     * - ``V4L2_DEEMPHASIS_DISABLED``
3270       - No de-emphasis is applied.
3271     * - ``V4L2_DEEMPHASIS_50_uS``
3272       - A de-emphasis of 50 uS is used.
3273     * - ``V4L2_DEEMPHASIS_75_uS``
3274       - A de-emphasis of 75 uS is used.
3275
3276
3277
3278
3279 .. _detect-controls:
3280
3281 Detect Control Reference
3282 ========================
3283
3284 The Detect class includes controls for common features of various motion
3285 or object detection capable devices.
3286
3287
3288 .. _detect-control-id:
3289
3290 Detect Control IDs
3291 ------------------
3292
3293 ``V4L2_CID_DETECT_CLASS (class)``
3294     The Detect class descriptor. Calling
3295     :ref:`VIDIOC_QUERYCTRL` for this control will
3296     return a description of this control class.
3297
3298 ``V4L2_CID_DETECT_MD_MODE (menu)``
3299     Sets the motion detection mode.
3300
3301 .. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
3302
3303 .. flat-table::
3304     :header-rows:  0
3305     :stub-columns: 0
3306
3307     * - ``V4L2_DETECT_MD_MODE_DISABLED``
3308       - Disable motion detection.
3309     * - ``V4L2_DETECT_MD_MODE_GLOBAL``
3310       - Use a single motion detection threshold.
3311     * - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
3312       - The image is divided into a grid, each cell with its own motion
3313         detection threshold. These thresholds are set through the
3314         ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
3315     * - ``V4L2_DETECT_MD_MODE_REGION_GRID``
3316       - The image is divided into a grid, each cell with its own region
3317         value that specifies which per-region motion detection thresholds
3318         should be used. Each region has its own thresholds. How these
3319         per-region thresholds are set up is driver-specific. The region
3320         values for the grid are set through the
3321         ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
3322
3323
3324
3325 ``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
3326     Sets the global motion detection threshold to be used with the
3327     ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
3328
3329 ``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
3330     Sets the motion detection thresholds for each cell in the grid. To
3331     be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
3332     detection mode. Matrix element (0, 0) represents the cell at the
3333     top-left of the grid.
3334
3335 ``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
3336     Sets the motion detection region value for each cell in the grid. To
3337     be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
3338     detection mode. Matrix element (0, 0) represents the cell at the
3339     top-left of the grid.
3340
3341
3342 .. _rf-tuner-controls:
3343
3344 RF Tuner Control Reference
3345 ==========================
3346
3347 The RF Tuner (RF_TUNER) class includes controls for common features of
3348 devices having RF tuner.
3349
3350 In this context, RF tuner is radio receiver circuit between antenna and
3351 demodulator. It receives radio frequency (RF) from the antenna and
3352 converts that received signal to lower intermediate frequency (IF) or
3353 baseband frequency (BB). Tuners that could do baseband output are often
3354 called Zero-IF tuners. Older tuners were typically simple PLL tuners
3355 inside a metal box, whilst newer ones are highly integrated chips
3356 without a metal box "silicon tuners". These controls are mostly
3357 applicable for new feature rich silicon tuners, just because older
3358 tuners does not have much adjustable features.
3359
3360 For more information about RF tuners see
3361 `Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
3362 and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
3363 from Wikipedia.
3364
3365
3366 .. _rf-tuner-control-id:
3367
3368 RF_TUNER Control IDs
3369 --------------------
3370
3371 ``V4L2_CID_RF_TUNER_CLASS (class)``
3372     The RF_TUNER class descriptor. Calling
3373     :ref:`VIDIOC_QUERYCTRL` for this control will
3374     return a description of this control class.
3375
3376 ``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
3377     Enables/disables tuner radio channel bandwidth configuration. In
3378     automatic mode bandwidth configuration is performed by the driver.
3379
3380 ``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
3381     Filter(s) on tuner signal path are used to filter signal according
3382     to receiving party needs. Driver configures filters to fulfill
3383     desired bandwidth requirement. Used when
3384     V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
3385     range and step are driver-specific.
3386
3387 ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
3388     Enables/disables LNA automatic gain control (AGC)
3389
3390 ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
3391     Enables/disables mixer automatic gain control (AGC)
3392
3393 ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
3394     Enables/disables IF automatic gain control (AGC)
3395
3396 ``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
3397     The RF amplifier is the very first amplifier on the receiver signal
3398     path, just right after the antenna input. The difference between the
3399     LNA gain and the RF gain in this document is that the LNA gain is
3400     integrated in the tuner chip while the RF gain is a separate chip.
3401     There may be both RF and LNA gain controls in the same device. The
3402     range and step are driver-specific.
3403
3404 ``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
3405     LNA (low noise amplifier) gain is first gain stage on the RF tuner
3406     signal path. It is located very close to tuner antenna input. Used
3407     when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
3408     ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
3409     differs from the each others. The range and step are
3410     driver-specific.
3411
3412 ``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
3413     Mixer gain is second gain stage on the RF tuner signal path. It is
3414     located inside mixer block, where RF signal is down-converted by the
3415     mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
3416     The range and step are driver-specific.
3417
3418 ``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
3419     IF gain is last gain stage on the RF tuner signal path. It is
3420     located on output of RF tuner. It controls signal level of
3421     intermediate frequency output or baseband output. Used when
3422     ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
3423     are driver-specific.
3424
3425 ``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
3426     Is synthesizer PLL locked? RF tuner is receiving given frequency
3427     when that control is set. This is a read-only control.
3428
3429 .. [#f1]
3430    This control may be changed to a menu control in the future, if more
3431    options are required.