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 :ref:`v4l2_ext_controls <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 :ref:`v4l2_ext_control <v4l2-ext-control>` array. The
  69 :ref:`struct v4l2_ext_control <v4l2-ext-control>` structure is very similar to
  70 struct :ref:`v4l2_control <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 :ref:`v4l2_ext_control <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:: These controls are applicable to all codecs and not just MPEG. The
 188    defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
 189    were originally made for MPEG codecs and later extended to cover all
 190    encoding formats.
 191
 192
 193 Generic Codec Controls
 194 ----------------------
 195
 196
 197 .. _mpeg-control-id:
 198
 199 Codec Control IDs
 200 ^^^^^^^^^^^^^^^^^
 201
 202 ``V4L2_CID_MPEG_CLASS (class)``
 203     The Codec class descriptor. Calling
 204     :ref:`VIDIOC_QUERYCTRL` for this control will
 205     return a description of this control class. This description can be
 206     used as the caption of a Tab page in a GUI, for example.
 207
 208 .. _v4l2-mpeg-stream-type:
 209
 210 ``V4L2_CID_MPEG_STREAM_TYPE (enum v4l2_mpeg_stream_type)``
 211     The MPEG-1, -2 or -4 output stream type. One cannot assume anything
 212     here. Each hardware MPEG encoder tends to support different subsets
 213     of the available MPEG stream types. This control is specific to
 214     multiplexed MPEG streams. The currently defined stream types are:
 215
 216
 217
 218 .. flat-table::
 219     :header-rows:  0
 220     :stub-columns: 0
 221
 222
 223     -  .. row 1
 224
 225        -  ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS``
 226
 227        -  MPEG-2 program stream
 228
 229     -  .. row 2
 230
 231        -  ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS``
 232
 233        -  MPEG-2 transport stream
 234
 235     -  .. row 3
 236
 237        -  ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS``
 238
 239        -  MPEG-1 system stream
 240
 241     -  .. row 4
 242
 243        -  ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD``
 244
 245        -  MPEG-2 DVD-compatible stream
 246
 247     -  .. row 5
 248
 249        -  ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD``
 250
 251        -  MPEG-1 VCD-compatible stream
 252
 253     -  .. row 6
 254
 255        -  ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD``
 256
 257        -  MPEG-2 SVCD-compatible stream
 258
 259
 260
 261 ``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
 262     Program Map Table Packet ID for the MPEG transport stream (default
 263     16)
 264
 265 ``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
 266     Audio Packet ID for the MPEG transport stream (default 256)
 267
 268 ``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
 269     Video Packet ID for the MPEG transport stream (default 260)
 270
 271 ``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
 272     Packet ID for the MPEG transport stream carrying PCR fields (default
 273     259)
 274
 275 ``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
 276     Audio ID for MPEG PES
 277
 278 ``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
 279     Video ID for MPEG PES
 280
 281 .. _v4l2-mpeg-stream-vbi-fmt:
 282
 283 ``V4L2_CID_MPEG_STREAM_VBI_FMT (enum v4l2_mpeg_stream_vbi_fmt)``
 284     Some cards can embed VBI data (e. g. Closed Caption, Teletext) into
 285     the MPEG stream. This control selects whether VBI data should be
 286     embedded, and if so, what embedding method should be used. The list
 287     of possible VBI formats depends on the driver. The currently defined
 288     VBI format types are:
 289
 290
 291
 292 .. flat-table::
 293     :header-rows:  0
 294     :stub-columns: 0
 295
 296
 297     -  .. row 1
 298
 299        -  ``V4L2_MPEG_STREAM_VBI_FMT_NONE``
 300
 301        -  No VBI in the MPEG stream
 302
 303     -  .. row 2
 304
 305        -  ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
 306
 307        -  VBI in private packets, IVTV format (documented in the kernel
 308           sources in the file
 309           ``Documentation/video4linux/cx2341x/README.vbi``)
 310
 311
 312
 313 .. _v4l2-mpeg-audio-sampling-freq:
 314
 315 ``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (enum v4l2_mpeg_audio_sampling_freq)``
 316     MPEG Audio sampling frequency. Possible values are:
 317
 318
 319
 320 .. flat-table::
 321     :header-rows:  0
 322     :stub-columns: 0
 323
 324
 325     -  .. row 1
 326
 327        -  ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
 328
 329        -  44.1 kHz
 330
 331     -  .. row 2
 332
 333        -  ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
 334
 335        -  48 kHz
 336
 337     -  .. row 3
 338
 339        -  ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
 340
 341        -  32 kHz
 342
 343
 344
 345 .. _v4l2-mpeg-audio-encoding:
 346
 347 ``V4L2_CID_MPEG_AUDIO_ENCODING (enum v4l2_mpeg_audio_encoding)``
 348     MPEG Audio encoding. This control is specific to multiplexed MPEG
 349     streams. Possible values are:
 350
 351
 352
 353 .. flat-table::
 354     :header-rows:  0
 355     :stub-columns: 0
 356
 357
 358     -  .. row 1
 359
 360        -  ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1``
 361
 362        -  MPEG-1/2 Layer I encoding
 363
 364     -  .. row 2
 365
 366        -  ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2``
 367
 368        -  MPEG-1/2 Layer II encoding
 369
 370     -  .. row 3
 371
 372        -  ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3``
 373
 374        -  MPEG-1/2 Layer III encoding
 375
 376     -  .. row 4
 377
 378        -  ``V4L2_MPEG_AUDIO_ENCODING_AAC``
 379
 380        -  MPEG-2/4 AAC (Advanced Audio Coding)
 381
 382     -  .. row 5
 383
 384        -  ``V4L2_MPEG_AUDIO_ENCODING_AC3``
 385
 386        -  AC-3 aka ATSC A/52 encoding
 387
 388
 389
 390 .. _v4l2-mpeg-audio-l1-bitrate:
 391
 392 ``V4L2_CID_MPEG_AUDIO_L1_BITRATE (enum v4l2_mpeg_audio_l1_bitrate)``
 393     MPEG-1/2 Layer I bitrate. Possible values are:
 394
 395
 396
 397 .. flat-table::
 398     :header-rows:  0
 399     :stub-columns: 0
 400
 401
 402     -  .. row 1
 403
 404        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
 405
 406        -  32 kbit/s
 407
 408     -  .. row 2
 409
 410        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
 411
 412        -  64 kbit/s
 413
 414     -  .. row 3
 415
 416        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
 417
 418        -  96 kbit/s
 419
 420     -  .. row 4
 421
 422        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
 423
 424        -  128 kbit/s
 425
 426     -  .. row 5
 427
 428        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
 429
 430        -  160 kbit/s
 431
 432     -  .. row 6
 433
 434        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
 435
 436        -  192 kbit/s
 437
 438     -  .. row 7
 439
 440        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
 441
 442        -  224 kbit/s
 443
 444     -  .. row 8
 445
 446        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
 447
 448        -  256 kbit/s
 449
 450     -  .. row 9
 451
 452        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
 453
 454        -  288 kbit/s
 455
 456     -  .. row 10
 457
 458        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
 459
 460        -  320 kbit/s
 461
 462     -  .. row 11
 463
 464        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
 465
 466        -  352 kbit/s
 467
 468     -  .. row 12
 469
 470        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
 471
 472        -  384 kbit/s
 473
 474     -  .. row 13
 475
 476        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
 477
 478        -  416 kbit/s
 479
 480     -  .. row 14
 481
 482        -  ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
 483
 484        -  448 kbit/s
 485
 486
 487
 488 .. _v4l2-mpeg-audio-l2-bitrate:
 489
 490 ``V4L2_CID_MPEG_AUDIO_L2_BITRATE (enum v4l2_mpeg_audio_l2_bitrate)``
 491     MPEG-1/2 Layer II bitrate. Possible values are:
 492
 493
 494
 495 .. flat-table::
 496     :header-rows:  0
 497     :stub-columns: 0
 498
 499
 500     -  .. row 1
 501
 502        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
 503
 504        -  32 kbit/s
 505
 506     -  .. row 2
 507
 508        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
 509
 510        -  48 kbit/s
 511
 512     -  .. row 3
 513
 514        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
 515
 516        -  56 kbit/s
 517
 518     -  .. row 4
 519
 520        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
 521
 522        -  64 kbit/s
 523
 524     -  .. row 5
 525
 526        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
 527
 528        -  80 kbit/s
 529
 530     -  .. row 6
 531
 532        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
 533
 534        -  96 kbit/s
 535
 536     -  .. row 7
 537
 538        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
 539
 540        -  112 kbit/s
 541
 542     -  .. row 8
 543
 544        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
 545
 546        -  128 kbit/s
 547
 548     -  .. row 9
 549
 550        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
 551
 552        -  160 kbit/s
 553
 554     -  .. row 10
 555
 556        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
 557
 558        -  192 kbit/s
 559
 560     -  .. row 11
 561
 562        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
 563
 564        -  224 kbit/s
 565
 566     -  .. row 12
 567
 568        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
 569
 570        -  256 kbit/s
 571
 572     -  .. row 13
 573
 574        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
 575
 576        -  320 kbit/s
 577
 578     -  .. row 14
 579
 580        -  ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
 581
 582        -  384 kbit/s
 583
 584
 585
 586 .. _v4l2-mpeg-audio-l3-bitrate:
 587
 588 ``V4L2_CID_MPEG_AUDIO_L3_BITRATE (enum v4l2_mpeg_audio_l3_bitrate)``
 589     MPEG-1/2 Layer III bitrate. Possible values are:
 590
 591
 592
 593 .. flat-table::
 594     :header-rows:  0
 595     :stub-columns: 0
 596
 597
 598     -  .. row 1
 599
 600        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
 601
 602        -  32 kbit/s
 603
 604     -  .. row 2
 605
 606        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
 607
 608        -  40 kbit/s
 609
 610     -  .. row 3
 611
 612        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
 613
 614        -  48 kbit/s
 615
 616     -  .. row 4
 617
 618        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
 619
 620        -  56 kbit/s
 621
 622     -  .. row 5
 623
 624        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
 625
 626        -  64 kbit/s
 627
 628     -  .. row 6
 629
 630        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
 631
 632        -  80 kbit/s
 633
 634     -  .. row 7
 635
 636        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
 637
 638        -  96 kbit/s
 639
 640     -  .. row 8
 641
 642        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
 643
 644        -  112 kbit/s
 645
 646     -  .. row 9
 647
 648        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
 649
 650        -  128 kbit/s
 651
 652     -  .. row 10
 653
 654        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
 655
 656        -  160 kbit/s
 657
 658     -  .. row 11
 659
 660        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
 661
 662        -  192 kbit/s
 663
 664     -  .. row 12
 665
 666        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
 667
 668        -  224 kbit/s
 669
 670     -  .. row 13
 671
 672        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
 673
 674        -  256 kbit/s
 675
 676     -  .. row 14
 677
 678        -  ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
 679
 680        -  320 kbit/s
 681
 682
 683
 684 ``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
 685     AAC bitrate in bits per second.
 686
 687 .. _v4l2-mpeg-audio-ac3-bitrate:
 688
 689 ``V4L2_CID_MPEG_AUDIO_AC3_BITRATE (enum v4l2_mpeg_audio_ac3_bitrate)``
 690     AC-3 bitrate. Possible values are:
 691
 692
 693
 694 .. flat-table::
 695     :header-rows:  0
 696     :stub-columns: 0
 697
 698
 699     -  .. row 1
 700
 701        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
 702
 703        -  32 kbit/s
 704
 705     -  .. row 2
 706
 707        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
 708
 709        -  40 kbit/s
 710
 711     -  .. row 3
 712
 713        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
 714
 715        -  48 kbit/s
 716
 717     -  .. row 4
 718
 719        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
 720
 721        -  56 kbit/s
 722
 723     -  .. row 5
 724
 725        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
 726
 727        -  64 kbit/s
 728
 729     -  .. row 6
 730
 731        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
 732
 733        -  80 kbit/s
 734
 735     -  .. row 7
 736
 737        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
 738
 739        -  96 kbit/s
 740
 741     -  .. row 8
 742
 743        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
 744
 745        -  112 kbit/s
 746
 747     -  .. row 9
 748
 749        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
 750
 751        -  128 kbit/s
 752
 753     -  .. row 10
 754
 755        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
 756
 757        -  160 kbit/s
 758
 759     -  .. row 11
 760
 761        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
 762
 763        -  192 kbit/s
 764
 765     -  .. row 12
 766
 767        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
 768
 769        -  224 kbit/s
 770
 771     -  .. row 13
 772
 773        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
 774
 775        -  256 kbit/s
 776
 777     -  .. row 14
 778
 779        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
 780
 781        -  320 kbit/s
 782
 783     -  .. row 15
 784
 785        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
 786
 787        -  384 kbit/s
 788
 789     -  .. row 16
 790
 791        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
 792
 793        -  448 kbit/s
 794
 795     -  .. row 17
 796
 797        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
 798
 799        -  512 kbit/s
 800
 801     -  .. row 18
 802
 803        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
 804
 805        -  576 kbit/s
 806
 807     -  .. row 19
 808
 809        -  ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
 810
 811        -  640 kbit/s
 812
 813
 814
 815 .. _v4l2-mpeg-audio-mode:
 816
 817 ``V4L2_CID_MPEG_AUDIO_MODE (enum v4l2_mpeg_audio_mode)``
 818     MPEG Audio mode. Possible values are:
 819
 820
 821
 822 .. flat-table::
 823     :header-rows:  0
 824     :stub-columns: 0
 825
 826
 827     -  .. row 1
 828
 829        -  ``V4L2_MPEG_AUDIO_MODE_STEREO``
 830
 831        -  Stereo
 832
 833     -  .. row 2
 834
 835        -  ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
 836
 837        -  Joint Stereo
 838
 839     -  .. row 3
 840
 841        -  ``V4L2_MPEG_AUDIO_MODE_DUAL``
 842
 843        -  Bilingual
 844
 845     -  .. row 4
 846
 847        -  ``V4L2_MPEG_AUDIO_MODE_MONO``
 848
 849        -  Mono
 850
 851
 852
 853 .. _v4l2-mpeg-audio-mode-extension:
 854
 855 ``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (enum v4l2_mpeg_audio_mode_extension)``
 856     Joint Stereo audio mode extension. In Layer I and II they indicate
 857     which subbands are in intensity stereo. All other subbands are coded
 858     in stereo. Layer III is not (yet) supported. Possible values are:
 859
 860
 861
 862 .. flat-table::
 863     :header-rows:  0
 864     :stub-columns: 0
 865
 866
 867     -  .. row 1
 868
 869        -  ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4``
 870
 871        -  Subbands 4-31 in intensity stereo
 872
 873     -  .. row 2
 874
 875        -  ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8``
 876
 877        -  Subbands 8-31 in intensity stereo
 878
 879     -  .. row 3
 880
 881        -  ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12``
 882
 883        -  Subbands 12-31 in intensity stereo
 884
 885     -  .. row 4
 886
 887        -  ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16``
 888
 889        -  Subbands 16-31 in intensity stereo
 890
 891
 892
 893 .. _v4l2-mpeg-audio-emphasis:
 894
 895 ``V4L2_CID_MPEG_AUDIO_EMPHASIS (enum v4l2_mpeg_audio_emphasis)``
 896     Audio Emphasis. Possible values are:
 897
 898
 899
 900 .. flat-table::
 901     :header-rows:  0
 902     :stub-columns: 0
 903
 904
 905     -  .. row 1
 906
 907        -  ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
 908
 909        -  None
 910
 911     -  .. row 2
 912
 913        -  ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
 914
 915        -  50/15 microsecond emphasis
 916
 917     -  .. row 3
 918
 919        -  ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
 920
 921        -  CCITT J.17
 922
 923
 924
 925 .. _v4l2-mpeg-audio-crc:
 926
 927 ``V4L2_CID_MPEG_AUDIO_CRC (enum v4l2_mpeg_audio_crc)``
 928     CRC method. Possible values are:
 929
 930
 931
 932 .. flat-table::
 933     :header-rows:  0
 934     :stub-columns: 0
 935
 936
 937     -  .. row 1
 938
 939        -  ``V4L2_MPEG_AUDIO_CRC_NONE``
 940
 941        -  None
 942
 943     -  .. row 2
 944
 945        -  ``V4L2_MPEG_AUDIO_CRC_CRC16``
 946
 947        -  16 bit parity check
 948
 949
 950
 951 ``V4L2_CID_MPEG_AUDIO_MUTE (boolean)``
 952     Mutes the audio when capturing. This is not done by muting audio
 953     hardware, which can still produce a slight hiss, but in the encoder
 954     itself, guaranteeing a fixed and reproducible audio bitstream. 0 =
 955     unmuted, 1 = muted.
 956
 957 .. _v4l2-mpeg-audio-dec-playback:
 958
 959 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
 960     Determines how monolingual audio should be played back. Possible
 961     values are:
 962
 963
 964
 965 .. flat-table::
 966     :header-rows:  0
 967     :stub-columns: 0
 968
 969
 970     -  .. row 1
 971
 972        -  ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
 973
 974        -  Automatically determines the best playback mode.
 975
 976     -  .. row 2
 977
 978        -  ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
 979
 980        -  Stereo playback.
 981
 982     -  .. row 3
 983
 984        -  ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT``
 985
 986        -  Left channel playback.
 987
 988     -  .. row 4
 989
 990        -  ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT``
 991
 992        -  Right channel playback.
 993
 994     -  .. row 5
 995
 996        -  ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO``
 997
 998        -  Mono playback.
 999
1000     -  .. row 6
1001
1002        -  ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
1003
1004        -  Stereo playback with swapped left and right channels.
1005
1006
1007
1008 .. _v4l2-mpeg-audio-dec-multilingual-playback:
1009
1010 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
1011     Determines how multilingual audio should be played back.
1012
1013 .. _v4l2-mpeg-video-encoding:
1014
1015 ``V4L2_CID_MPEG_VIDEO_ENCODING (enum v4l2_mpeg_video_encoding)``
1016     MPEG Video encoding method. This control is specific to multiplexed
1017     MPEG streams. Possible values are:
1018
1019
1020
1021 .. flat-table::
1022     :header-rows:  0
1023     :stub-columns: 0
1024
1025
1026     -  .. row 1
1027
1028        -  ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1``
1029
1030        -  MPEG-1 Video encoding
1031
1032     -  .. row 2
1033
1034        -  ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2``
1035
1036        -  MPEG-2 Video encoding
1037
1038     -  .. row 3
1039
1040        -  ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC``
1041
1042        -  MPEG-4 AVC (H.264) Video encoding
1043
1044
1045
1046 .. _v4l2-mpeg-video-aspect:
1047
1048 ``V4L2_CID_MPEG_VIDEO_ASPECT (enum v4l2_mpeg_video_aspect)``
1049     Video aspect. Possible values are:
1050
1051
1052
1053 .. flat-table::
1054     :header-rows:  0
1055     :stub-columns: 0
1056
1057
1058     -  .. row 1
1059
1060        -  ``V4L2_MPEG_VIDEO_ASPECT_1x1``
1061
1062     -  .. row 2
1063
1064        -  ``V4L2_MPEG_VIDEO_ASPECT_4x3``
1065
1066     -  .. row 3
1067
1068        -  ``V4L2_MPEG_VIDEO_ASPECT_16x9``
1069
1070     -  .. row 4
1071
1072        -  ``V4L2_MPEG_VIDEO_ASPECT_221x100``
1073
1074
1075
1076 ``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
1077     Number of B-Frames (default 2)
1078
1079 ``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
1080     GOP size (default 12)
1081
1082 ``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
1083     GOP closure (default 1)
1084
1085 ``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
1086     Enable 3:2 pulldown (default 0)
1087
1088 .. _v4l2-mpeg-video-bitrate-mode:
1089
1090 ``V4L2_CID_MPEG_VIDEO_BITRATE_MODE (enum v4l2_mpeg_video_bitrate_mode)``
1091     Video bitrate mode. Possible values are:
1092
1093
1094
1095 .. flat-table::
1096     :header-rows:  0
1097     :stub-columns: 0
1098
1099
1100     -  .. row 1
1101
1102        -  ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
1103
1104        -  Variable bitrate
1105
1106     -  .. row 2
1107
1108        -  ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
1109
1110        -  Constant bitrate
1111
1112
1113
1114 ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
1115     Video bitrate in bits per second.
1116
1117 ``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)``
1118     Peak video bitrate in bits per second. Must be larger or equal to
1119     the average video bitrate. It is ignored if the video bitrate mode
1120     is set to constant bitrate.
1121
1122 ``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)``
1123     For every captured frame, skip this many subsequent frames (default
1124     0).
1125
1126 ``V4L2_CID_MPEG_VIDEO_MUTE (boolean)``
1127     "Mutes" the video to a fixed color when capturing. This is useful
1128     for testing, to produce a fixed video bitstream. 0 = unmuted, 1 =
1129     muted.
1130
1131 ``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)``
1132     Sets the "mute" color of the video. The supplied 32-bit integer is
1133     interpreted as follows (bit 0 = least significant bit):
1134
1135
1136
1137 .. flat-table::
1138     :header-rows:  0
1139     :stub-columns: 0
1140
1141
1142     -  .. row 1
1143
1144        -  Bit 0:7
1145
1146        -  V chrominance information
1147
1148     -  .. row 2
1149
1150        -  Bit 8:15
1151
1152        -  U chrominance information
1153
1154     -  .. row 3
1155
1156        -  Bit 16:23
1157
1158        -  Y luminance information
1159
1160     -  .. row 4
1161
1162        -  Bit 24:31
1163
1164        -  Must be zero.
1165
1166
1167
1168 .. _v4l2-mpeg-video-dec-pts:
1169
1170 ``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)``
1171     This read-only control returns the 33-bit video Presentation Time
1172     Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the
1173     currently displayed frame. This is the same PTS as is used in
1174     :ref:`VIDIOC_DECODER_CMD`.
1175
1176 .. _v4l2-mpeg-video-dec-frame:
1177
1178 ``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)``
1179     This read-only control returns the frame counter of the frame that
1180     is currently displayed (decoded). This value is reset to 0 whenever
1181     the decoder is started.
1182
1183 ``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)``
1184     If enabled the decoder expects to receive a single slice per buffer,
1185     otherwise the decoder expects a single frame in per buffer.
1186     Applicable to the decoder, all codecs.
1187
1188 ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)``
1189     Enable writing sample aspect ratio in the Video Usability
1190     Information. Applicable to the H264 encoder.
1191
1192 .. _v4l2-mpeg-video-h264-vui-sar-idc:
1193
1194 ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC (enum v4l2_mpeg_video_h264_vui_sar_idc)``
1195     VUI sample aspect ratio indicator for H.264 encoding. The value is
1196     defined in the table E-1 in the standard. Applicable to the H264
1197     encoder.
1198
1199
1200
1201 .. flat-table::
1202     :header-rows:  0
1203     :stub-columns: 0
1204
1205
1206     -  .. row 1
1207
1208        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
1209
1210        -  Unspecified
1211
1212     -  .. row 2
1213
1214        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
1215
1216        -  1x1
1217
1218     -  .. row 3
1219
1220        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
1221
1222        -  12x11
1223
1224     -  .. row 4
1225
1226        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
1227
1228        -  10x11
1229
1230     -  .. row 5
1231
1232        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
1233
1234        -  16x11
1235
1236     -  .. row 6
1237
1238        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
1239
1240        -  40x33
1241
1242     -  .. row 7
1243
1244        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
1245
1246        -  24x11
1247
1248     -  .. row 8
1249
1250        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
1251
1252        -  20x11
1253
1254     -  .. row 9
1255
1256        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
1257
1258        -  32x11
1259
1260     -  .. row 10
1261
1262        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
1263
1264        -  80x33
1265
1266     -  .. row 11
1267
1268        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
1269
1270        -  18x11
1271
1272     -  .. row 12
1273
1274        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
1275
1276        -  15x11
1277
1278     -  .. row 13
1279
1280        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
1281
1282        -  64x33
1283
1284     -  .. row 14
1285
1286        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
1287
1288        -  160x99
1289
1290     -  .. row 15
1291
1292        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
1293
1294        -  4x3
1295
1296     -  .. row 16
1297
1298        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
1299
1300        -  3x2
1301
1302     -  .. row 17
1303
1304        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
1305
1306        -  2x1
1307
1308     -  .. row 18
1309
1310        -  ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
1311
1312        -  Extended SAR
1313
1314
1315
1316 ``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)``
1317     Extended sample aspect ratio width for H.264 VUI encoding.
1318     Applicable to the H264 encoder.
1319
1320 ``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)``
1321     Extended sample aspect ratio height for H.264 VUI encoding.
1322     Applicable to the H264 encoder.
1323
1324 .. _v4l2-mpeg-video-h264-level:
1325
1326 ``V4L2_CID_MPEG_VIDEO_H264_LEVEL (enum v4l2_mpeg_video_h264_level)``
1327     The level information for the H264 video elementary stream.
1328     Applicable to the H264 encoder. Possible values are:
1329
1330
1331
1332 .. flat-table::
1333     :header-rows:  0
1334     :stub-columns: 0
1335
1336
1337     -  .. row 1
1338
1339        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
1340
1341        -  Level 1.0
1342
1343     -  .. row 2
1344
1345        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
1346
1347        -  Level 1B
1348
1349     -  .. row 3
1350
1351        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
1352
1353        -  Level 1.1
1354
1355     -  .. row 4
1356
1357        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
1358
1359        -  Level 1.2
1360
1361     -  .. row 5
1362
1363        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
1364
1365        -  Level 1.3
1366
1367     -  .. row 6
1368
1369        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
1370
1371        -  Level 2.0
1372
1373     -  .. row 7
1374
1375        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
1376
1377        -  Level 2.1
1378
1379     -  .. row 8
1380
1381        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
1382
1383        -  Level 2.2
1384
1385     -  .. row 9
1386
1387        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
1388
1389        -  Level 3.0
1390
1391     -  .. row 10
1392
1393        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
1394
1395        -  Level 3.1
1396
1397     -  .. row 11
1398
1399        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
1400
1401        -  Level 3.2
1402
1403     -  .. row 12
1404
1405        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
1406
1407        -  Level 4.0
1408
1409     -  .. row 13
1410
1411        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
1412
1413        -  Level 4.1
1414
1415     -  .. row 14
1416
1417        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
1418
1419        -  Level 4.2
1420
1421     -  .. row 15
1422
1423        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
1424
1425        -  Level 5.0
1426
1427     -  .. row 16
1428
1429        -  ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
1430
1431        -  Level 5.1
1432
1433
1434
1435 .. _v4l2-mpeg-video-mpeg4-level:
1436
1437 ``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL (enum v4l2_mpeg_video_mpeg4_level)``
1438     The level information for the MPEG4 elementary stream. Applicable to
1439     the MPEG4 encoder. Possible values are:
1440
1441
1442
1443 .. flat-table::
1444     :header-rows:  0
1445     :stub-columns: 0
1446
1447
1448     -  .. row 1
1449
1450        -  ``V4L2_MPEG_VIDEO_LEVEL_0``
1451
1452        -  Level 0
1453
1454     -  .. row 2
1455
1456        -  ``V4L2_MPEG_VIDEO_LEVEL_0B``
1457
1458        -  Level 0b
1459
1460     -  .. row 3
1461
1462        -  ``V4L2_MPEG_VIDEO_LEVEL_1``
1463
1464        -  Level 1
1465
1466     -  .. row 4
1467
1468        -  ``V4L2_MPEG_VIDEO_LEVEL_2``
1469
1470        -  Level 2
1471
1472     -  .. row 5
1473
1474        -  ``V4L2_MPEG_VIDEO_LEVEL_3``
1475
1476        -  Level 3
1477
1478     -  .. row 6
1479
1480        -  ``V4L2_MPEG_VIDEO_LEVEL_3B``
1481
1482        -  Level 3b
1483
1484     -  .. row 7
1485
1486        -  ``V4L2_MPEG_VIDEO_LEVEL_4``
1487
1488        -  Level 4
1489
1490     -  .. row 8
1491
1492        -  ``V4L2_MPEG_VIDEO_LEVEL_5``
1493
1494        -  Level 5
1495
1496
1497
1498 .. _v4l2-mpeg-video-h264-profile:
1499
1500 ``V4L2_CID_MPEG_VIDEO_H264_PROFILE (enum v4l2_mpeg_video_h264_profile)``
1501     The profile information for H264. Applicable to the H264 encoder.
1502     Possible values are:
1503
1504
1505
1506 .. flat-table::
1507     :header-rows:  0
1508     :stub-columns: 0
1509
1510
1511     -  .. row 1
1512
1513        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
1514
1515        -  Baseline profile
1516
1517     -  .. row 2
1518
1519        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
1520
1521        -  Constrained Baseline profile
1522
1523     -  .. row 3
1524
1525        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
1526
1527        -  Main profile
1528
1529     -  .. row 4
1530
1531        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
1532
1533        -  Extended profile
1534
1535     -  .. row 5
1536
1537        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
1538
1539        -  High profile
1540
1541     -  .. row 6
1542
1543        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
1544
1545        -  High 10 profile
1546
1547     -  .. row 7
1548
1549        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
1550
1551        -  High 422 profile
1552
1553     -  .. row 8
1554
1555        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE``
1556
1557        -  High 444 Predictive profile
1558
1559     -  .. row 9
1560
1561        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA``
1562
1563        -  High 10 Intra profile
1564
1565     -  .. row 10
1566
1567        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA``
1568
1569        -  High 422 Intra profile
1570
1571     -  .. row 11
1572
1573        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA``
1574
1575        -  High 444 Intra profile
1576
1577     -  .. row 12
1578
1579        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA``
1580
1581        -  CAVLC 444 Intra profile
1582
1583     -  .. row 13
1584
1585        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE``
1586
1587        -  Scalable Baseline profile
1588
1589     -  .. row 14
1590
1591        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH``
1592
1593        -  Scalable High profile
1594
1595     -  .. row 15
1596
1597        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA``
1598
1599        -  Scalable High Intra profile
1600
1601     -  .. row 16
1602
1603        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH``
1604
1605        -  Stereo High profile
1606
1607     -  .. row 17
1608
1609        -  ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH``
1610
1611        -  Multiview High profile
1612
1613
1614
1615 .. _v4l2-mpeg-video-mpeg4-profile:
1616
1617 ``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE (enum v4l2_mpeg_video_mpeg4_profile)``
1618     The profile information for MPEG4. Applicable to the MPEG4 encoder.
1619     Possible values are:
1620
1621
1622
1623 .. flat-table::
1624     :header-rows:  0
1625     :stub-columns: 0
1626
1627
1628     -  .. row 1
1629
1630        -  ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE``
1631
1632        -  Simple profile
1633
1634     -  .. row 2
1635
1636        -  ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE``
1637
1638        -  Advanced Simple profile
1639
1640     -  .. row 3
1641
1642        -  ``V4L2_MPEG_VIDEO_PROFILE_CORE``
1643
1644        -  Core profile
1645
1646     -  .. row 4
1647
1648        -  ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE``
1649
1650        -  Simple Scalable profile
1651
1652     -  .. row 5
1653
1654        -  ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY``
1655
1656        -
1657
1658
1659
1660 ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
1661     The maximum number of reference pictures used for encoding.
1662     Applicable to the encoder.
1663
1664 .. _v4l2-mpeg-video-multi-slice-mode:
1665
1666 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE (enum v4l2_mpeg_video_multi_slice_mode)``
1667     Determines how the encoder should handle division of frame into
1668     slices. Applicable to the encoder. Possible values are:
1669
1670
1671
1672 .. flat-table::
1673     :header-rows:  0
1674     :stub-columns: 0
1675
1676
1677     -  .. row 1
1678
1679        -  ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE``
1680
1681        -  Single slice per frame.
1682
1683     -  .. row 2
1684
1685        -  ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``
1686
1687        -  Multiple slices with set maximum number of macroblocks per slice.
1688
1689     -  .. row 3
1690
1691        -  ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``
1692
1693        -  Multiple slice with set maximum size in bytes per slice.
1694
1695
1696
1697 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)``
1698     The maximum number of macroblocks in a slice. Used when
1699     ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
1700     ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the
1701     encoder.
1702
1703 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)``
1704     The maximum size of a slice in bytes. Used when
1705     ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
1706     ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the
1707     encoder.
1708
1709 .. _v4l2-mpeg-video-h264-loop-filter-mode:
1710
1711 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE (enum v4l2_mpeg_video_h264_loop_filter_mode)``
1712     Loop filter mode for H264 encoder. Possible values are:
1713
1714
1715
1716 .. flat-table::
1717     :header-rows:  0
1718     :stub-columns: 0
1719
1720
1721     -  .. row 1
1722
1723        -  ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED``
1724
1725        -  Loop filter is enabled.
1726
1727     -  .. row 2
1728
1729        -  ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED``
1730
1731        -  Loop filter is disabled.
1732
1733     -  .. row 3
1734
1735        -  ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
1736
1737        -  Loop filter is disabled at the slice boundary.
1738
1739
1740
1741 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)``
1742     Loop filter alpha coefficient, defined in the H264 standard.
1743     Applicable to the H264 encoder.
1744
1745 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)``
1746     Loop filter beta coefficient, defined in the H264 standard.
1747     Applicable to the H264 encoder.
1748
1749 .. _v4l2-mpeg-video-h264-entropy-mode:
1750
1751 ``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE (enum v4l2_mpeg_video_h264_entropy_mode)``
1752     Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264
1753     encoder. Possible values are:
1754
1755
1756
1757 .. flat-table::
1758     :header-rows:  0
1759     :stub-columns: 0
1760
1761
1762     -  .. row 1
1763
1764        -  ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC``
1765
1766        -  Use CAVLC entropy coding.
1767
1768     -  .. row 2
1769
1770        -  ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC``
1771
1772        -  Use CABAC entropy coding.
1773
1774
1775
1776 ``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
1777     Enable 8X8 transform for H264. Applicable to the H264 encoder.
1778
1779 ``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)``
1780     Cyclic intra macroblock refresh. This is the number of continuous
1781     macroblocks refreshed every frame. Each frame a successive set of
1782     macroblocks is refreshed until the cycle completes and starts from
1783     the top of the frame. Applicable to H264, H263 and MPEG4 encoder.
1784
1785 ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)``
1786     Frame level rate control enable. If this control is disabled then
1787     the quantization parameter for each frame type is constant and set
1788     with appropriate controls (e.g.
1789     ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is
1790     enabled then quantization parameter is adjusted to meet the chosen
1791     bitrate. Minimum and maximum value for the quantization parameter
1792     can be set with appropriate controls (e.g.
1793     ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders.
1794
1795 ``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
1796     Macroblock level rate control enable. Applicable to the MPEG4 and
1797     H264 encoders.
1798
1799 ``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
1800     Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
1801     encoder.
1802
1803 ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
1804     Quantization parameter for an I frame for H263. Valid range: from 1
1805     to 31.
1806
1807 ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
1808     Minimum quantization parameter for H263. Valid range: from 1 to 31.
1809
1810 ``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
1811     Maximum quantization parameter for H263. Valid range: from 1 to 31.
1812
1813 ``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
1814     Quantization parameter for an P frame for H263. Valid range: from 1
1815     to 31.
1816
1817 ``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
1818     Quantization parameter for an B frame for H263. Valid range: from 1
1819     to 31.
1820
1821 ``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
1822     Quantization parameter for an I frame for H264. Valid range: from 0
1823     to 51.
1824
1825 ``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
1826     Minimum quantization parameter for H264. Valid range: from 0 to 51.
1827
1828 ``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
1829     Maximum quantization parameter for H264. Valid range: from 0 to 51.
1830
1831 ``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
1832     Quantization parameter for an P frame for H264. Valid range: from 0
1833     to 51.
1834
1835 ``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
1836     Quantization parameter for an B frame for H264. Valid range: from 0
1837     to 51.
1838
1839 ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
1840     Quantization parameter for an I frame for MPEG4. Valid range: from 1
1841     to 31.
1842
1843 ``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
1844     Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
1845
1846 ``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
1847     Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
1848
1849 ``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
1850     Quantization parameter for an P frame for MPEG4. Valid range: from 1
1851     to 31.
1852
1853 ``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
1854     Quantization parameter for an B frame for MPEG4. Valid range: from 1
1855     to 31.
1856
1857 ``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)``
1858     The Video Buffer Verifier size in kilobytes, it is used as a
1859     limitation of frame skip. The VBV is defined in the standard as a
1860     mean to verify that the produced stream will be successfully
1861     decoded. The standard describes it as "Part of a hypothetical
1862     decoder that is conceptually connected to the output of the encoder.
1863     Its purpose is to provide a constraint on the variability of the
1864     data rate that an encoder or editing process may produce.".
1865     Applicable to the MPEG1, MPEG2, MPEG4 encoders.
1866
1867 .. _v4l2-mpeg-video-vbv-delay:
1868
1869 ``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
1870     Sets the initial delay in milliseconds for VBV buffer control.
1871
1872 .. _v4l2-mpeg-video-hor-search-range:
1873
1874 ``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)``
1875     Horizontal search range defines maximum horizontal search area in
1876     pixels to search and match for the present Macroblock (MB) in the
1877     reference picture. This V4L2 control macro is used to set horizontal
1878     search range for motion estimation module in video encoder.
1879
1880 .. _v4l2-mpeg-video-vert-search-range:
1881
1882 ``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)``
1883     Vertical search range defines maximum vertical search area in pixels
1884     to search and match for the present Macroblock (MB) in the reference
1885     picture. This V4L2 control macro is used to set vertical search
1886     range for motion estimation module in video encoder.
1887
1888 .. _v4l2-mpeg-video-force-key-frame:
1889
1890 ``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)``
1891     Force a key frame for the next queued buffer. Applicable to
1892     encoders. This is a general, codec-agnostic keyframe control.
1893
1894 ``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)``
1895     The Coded Picture Buffer size in kilobytes, it is used as a
1896     limitation of frame skip. The CPB is defined in the H264 standard as
1897     a mean to verify that the produced stream will be successfully
1898     decoded. Applicable to the H264 encoder.
1899
1900 ``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)``
1901     Period between I-frames in the open GOP for H264. In case of an open
1902     GOP this is the period between two I-frames. The period between IDR
1903     (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE
1904     control. An IDR frame, which stands for Instantaneous Decoding
1905     Refresh is an I-frame after which no prior frames are referenced.
1906     This means that a stream can be restarted from an IDR frame without
1907     the need to store or decode any previous frames. Applicable to the
1908     H264 encoder.
1909
1910 .. _v4l2-mpeg-video-header-mode:
1911
1912 ``V4L2_CID_MPEG_VIDEO_HEADER_MODE (enum v4l2_mpeg_video_header_mode)``
1913     Determines whether the header is returned as the first buffer or is
1914     it returned together with the first frame. Applicable to encoders.
1915     Possible values are:
1916
1917
1918
1919 .. flat-table::
1920     :header-rows:  0
1921     :stub-columns: 0
1922
1923
1924     -  .. row 1
1925
1926        -  ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE``
1927
1928        -  The stream header is returned separately in the first buffer.
1929
1930     -  .. row 2
1931
1932        -  ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME``
1933
1934        -  The stream header is returned together with the first encoded
1935           frame.
1936
1937
1938
1939 ``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)``
1940     Repeat the video sequence headers. Repeating these headers makes
1941     random access to the video stream easier. Applicable to the MPEG1, 2
1942     and 4 encoder.
1943
1944 ``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)``
1945     Enabled the deblocking post processing filter for MPEG4 decoder.
1946     Applicable to the MPEG4 decoder.
1947
1948 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
1949     vop_time_increment_resolution value for MPEG4. Applicable to the
1950     MPEG4 encoder.
1951
1952 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
1953     vop_time_increment value for MPEG4. Applicable to the MPEG4
1954     encoder.
1955
1956 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)``
1957     Enable generation of frame packing supplemental enhancement
1958     information in the encoded bitstream. The frame packing SEI message
1959     contains the arrangement of L and R planes for 3D viewing.
1960     Applicable to the H264 encoder.
1961
1962 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)``
1963     Sets current frame as frame0 in frame packing SEI. Applicable to the
1964     H264 encoder.
1965
1966 .. _v4l2-mpeg-video-h264-sei-fp-arrangement-type:
1967
1968 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE (enum v4l2_mpeg_video_h264_sei_fp_arrangement_type)``
1969     Frame packing arrangement type for H264 SEI. Applicable to the H264
1970     encoder. Possible values are:
1971
1972
1973
1974 .. flat-table::
1975     :header-rows:  0
1976     :stub-columns: 0
1977
1978
1979     -  .. row 1
1980
1981        -  ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD``
1982
1983        -  Pixels are alternatively from L and R.
1984
1985     -  .. row 2
1986
1987        -  ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN``
1988
1989        -  L and R are interlaced by column.
1990
1991     -  .. row 3
1992
1993        -  ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW``
1994
1995        -  L and R are interlaced by row.
1996
1997     -  .. row 4
1998
1999        -  ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE``
2000
2001        -  L is on the left, R on the right.
2002
2003     -  .. row 5
2004
2005        -  ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM``
2006
2007        -  L is on top, R on bottom.
2008
2009     -  .. row 6
2010
2011        -  ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL``
2012
2013        -  One view per frame.
2014
2015
2016
2017 ``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)``
2018     Enables flexible macroblock ordering in the encoded bitstream. It is
2019     a technique used for restructuring the ordering of macroblocks in
2020     pictures. Applicable to the H264 encoder.
2021
2022 .. _v4l2-mpeg-video-h264-fmo-map-type:
2023
2024 ``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE (enum v4l2_mpeg_video_h264_fmo_map_type)``
2025     When using FMO, the map type divides the image in different scan
2026     patterns of macroblocks. Applicable to the H264 encoder. Possible
2027     values are:
2028
2029
2030
2031 .. flat-table::
2032     :header-rows:  0
2033     :stub-columns: 0
2034
2035
2036     -  .. row 1
2037
2038        -  ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
2039
2040        -  Slices are interleaved one after other with macroblocks in run
2041           length order.
2042
2043     -  .. row 2
2044
2045        -  ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES``
2046
2047        -  Scatters the macroblocks based on a mathematical function known to
2048           both encoder and decoder.
2049
2050     -  .. row 3
2051
2052        -  ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER``
2053
2054        -  Macroblocks arranged in rectangular areas or regions of interest.
2055
2056     -  .. row 4
2057
2058        -  ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT``
2059
2060        -  Slice groups grow in a cyclic way from centre to outwards.
2061
2062     -  .. row 5
2063
2064        -  ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN``
2065
2066        -  Slice groups grow in raster scan pattern from left to right.
2067
2068     -  .. row 6
2069
2070        -  ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN``
2071
2072        -  Slice groups grow in wipe scan pattern from top to bottom.
2073
2074     -  .. row 7
2075
2076        -  ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT``
2077
2078        -  User defined map type.
2079
2080
2081
2082 ``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
2083     Number of slice groups in FMO. Applicable to the H264 encoder.
2084
2085 .. _v4l2-mpeg-video-h264-fmo-change-direction:
2086
2087 ``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION (enum v4l2_mpeg_video_h264_fmo_change_dir)``
2088     Specifies a direction of the slice group change for raster and wipe
2089     maps. Applicable to the H264 encoder. Possible values are:
2090
2091
2092
2093 .. flat-table::
2094     :header-rows:  0
2095     :stub-columns: 0
2096
2097
2098     -  .. row 1
2099
2100        -  ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT``
2101
2102        -  Raster scan or wipe right.
2103
2104     -  .. row 2
2105
2106        -  ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT``
2107
2108        -  Reverse raster scan or wipe left.
2109
2110
2111
2112 ``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)``
2113     Specifies the size of the first slice group for raster and wipe map.
2114     Applicable to the H264 encoder.
2115
2116 ``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)``
2117     Specifies the number of consecutive macroblocks for the interleaved
2118     map. Applicable to the H264 encoder.
2119
2120 ``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
2121     Enables arbitrary slice ordering in encoded bitstream. Applicable to
2122     the H264 encoder.
2123
2124 ``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)``
2125     Specifies the slice order in ASO. Applicable to the H264 encoder.
2126     The supplied 32-bit integer is interpreted as follows (bit 0 = least
2127     significant bit):
2128
2129
2130
2131 .. flat-table::
2132     :header-rows:  0
2133     :stub-columns: 0
2134
2135
2136     -  .. row 1
2137
2138        -  Bit 0:15
2139
2140        -  Slice ID
2141
2142     -  .. row 2
2143
2144        -  Bit 16:32
2145
2146        -  Slice position or order
2147
2148
2149
2150 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
2151     Enables H264 hierarchical coding. Applicable to the H264 encoder.
2152
2153 .. _v4l2-mpeg-video-h264-hierarchical-coding-type:
2154
2155 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE (enum v4l2_mpeg_video_h264_hierarchical_coding_type)``
2156     Specifies the hierarchical coding type. Applicable to the H264
2157     encoder. Possible values are:
2158
2159
2160
2161 .. flat-table::
2162     :header-rows:  0
2163     :stub-columns: 0
2164
2165
2166     -  .. row 1
2167
2168        -  ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
2169
2170        -  Hierarchical B coding.
2171
2172     -  .. row 2
2173
2174        -  ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
2175
2176        -  Hierarchical P coding.
2177
2178
2179
2180 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
2181     Specifies the number of hierarchical coding layers. Applicable to
2182     the H264 encoder.
2183
2184 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)``
2185     Specifies a user defined QP for each layer. Applicable to the H264
2186     encoder. The supplied 32-bit integer is interpreted as follows (bit
2187     0 = least significant bit):
2188
2189
2190
2191 .. flat-table::
2192     :header-rows:  0
2193     :stub-columns: 0
2194
2195
2196     -  .. row 1
2197
2198        -  Bit 0:15
2199
2200        -  QP value
2201
2202     -  .. row 2
2203
2204        -  Bit 16:32
2205
2206        -  Layer number
2207
2208
2209
2210
2211 MFC 5.1 MPEG Controls
2212 ---------------------
2213
2214 The following MPEG class controls deal with MPEG decoding and encoding
2215 settings that are specific to the Multi Format Codec 5.1 device present
2216 in the S5P family of SoCs by Samsung.
2217
2218
2219 .. _mfc51-control-id:
2220
2221 MFC 5.1 Control IDs
2222 ^^^^^^^^^^^^^^^^^^^
2223
2224 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)``
2225     If the display delay is enabled then the decoder is forced to return
2226     a CAPTURE buffer (decoded frame) after processing a certain number
2227     of OUTPUT buffers. The delay can be set through
2228     ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This
2229     feature can be used for example for generating thumbnails of videos.
2230     Applicable to the H264 decoder.
2231
2232 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)``
2233     Display delay value for H264 decoder. The decoder is forced to
2234     return a decoded frame after the set 'display delay' number of
2235     frames. If this number is low it may result in frames returned out
2236     of dispaly order, in addition the hardware may still be using the
2237     returned buffer as a reference picture for subsequent frames.
2238
2239 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)``
2240     The number of reference pictures used for encoding a P picture.
2241     Applicable to the H264 encoder.
2242
2243 ``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)``
2244     Padding enable in the encoder - use a color instead of repeating
2245     border pixels. Applicable to encoders.
2246
2247 ``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)``
2248     Padding color in the encoder. Applicable to encoders. The supplied
2249     32-bit integer is interpreted as follows (bit 0 = least significant
2250     bit):
2251
2252
2253
2254 .. flat-table::
2255     :header-rows:  0
2256     :stub-columns: 0
2257
2258
2259     -  .. row 1
2260
2261        -  Bit 0:7
2262
2263        -  V chrominance information
2264
2265     -  .. row 2
2266
2267        -  Bit 8:15
2268
2269        -  U chrominance information
2270
2271     -  .. row 3
2272
2273        -  Bit 16:23
2274
2275        -  Y luminance information
2276
2277     -  .. row 4
2278
2279        -  Bit 24:31
2280
2281        -  Must be zero.
2282
2283
2284
2285 ``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
2286     Reaction coefficient for MFC rate control. Applicable to encoders.
2287
2288     .. note::
2289
2290        #. Valid only when the frame level RC is enabled.
2291
2292        #. For tight CBR, this field must be small (ex. 2 ~ 10). For
2293           VBR, this field must be large (ex. 100 ~ 1000).
2294
2295        #. It is not recommended to use the greater number than
2296           FRAME_RATE * (10^9 / BIT_RATE).
2297
2298 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
2299     Adaptive rate control for dark region. Valid only when H.264 and
2300     macroblock level RC is enabled
2301     (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2302     encoder.
2303
2304 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)``
2305     Adaptive rate control for smooth region. Valid only when H.264 and
2306     macroblock level RC is enabled
2307     (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2308     encoder.
2309
2310 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)``
2311     Adaptive rate control for static region. Valid only when H.264 and
2312     macroblock level RC is enabled
2313     (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2314     encoder.
2315
2316 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)``
2317     Adaptive rate control for activity region. Valid only when H.264 and
2318     macroblock level RC is enabled
2319     (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2320     encoder.
2321
2322 .. _v4l2-mpeg-mfc51-video-frame-skip-mode:
2323
2324 ``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE (enum v4l2_mpeg_mfc51_video_frame_skip_mode)``
2325     Indicates in what conditions the encoder should skip frames. If
2326     encoding a frame would cause the encoded stream to be larger then a
2327     chosen data limit then the frame will be skipped. Possible values
2328     are:
2329
2330
2331
2332 .. flat-table::
2333     :header-rows:  0
2334     :stub-columns: 0
2335
2336
2337     -  .. row 1
2338
2339        -  ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED``
2340
2341        -  Frame skip mode is disabled.
2342
2343     -  .. row 2
2344
2345        -  ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT``
2346
2347        -  Frame skip mode enabled and buffer limit is set by the chosen
2348           level and is defined by the standard.
2349
2350     -  .. row 3
2351
2352        -  ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT``
2353
2354        -  Frame skip mode enabled and buffer limit is set by the VBV
2355           (MPEG1/2/4) or CPB (H264) buffer size control.
2356
2357
2358
2359 ``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)``
2360     Enable rate-control with fixed target bit. If this setting is
2361     enabled, then the rate control logic of the encoder will calculate
2362     the average bitrate for a GOP and keep it below or equal the set
2363     bitrate target. Otherwise the rate control logic calculates the
2364     overall average bitrate for the stream and keeps it below or equal
2365     to the set bitrate. In the first case the average bitrate for the
2366     whole stream will be smaller then the set bitrate. This is caused
2367     because the average is calculated for smaller number of frames, on
2368     the other hand enabling this setting will ensure that the stream
2369     will meet tight bandwidth constraints. Applicable to encoders.
2370
2371 .. _v4l2-mpeg-mfc51-video-force-frame-type:
2372
2373 ``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE (enum v4l2_mpeg_mfc51_video_force_frame_type)``
2374     Force a frame type for the next queued buffer. Applicable to
2375     encoders. Possible values are:
2376
2377
2378
2379 .. flat-table::
2380     :header-rows:  0
2381     :stub-columns: 0
2382
2383
2384     -  .. row 1
2385
2386        -  ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
2387
2388        -  Forcing a specific frame type disabled.
2389
2390     -  .. row 2
2391
2392        -  ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
2393
2394        -  Force an I-frame.
2395
2396     -  .. row 3
2397
2398        -  ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
2399
2400        -  Force a non-coded frame.
2401
2402
2403
2404
2405 CX2341x MPEG Controls
2406 ---------------------
2407
2408 The following MPEG class controls deal with MPEG encoding settings that
2409 are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
2410
2411
2412 .. _cx2341x-control-id:
2413
2414 CX2341x Control IDs
2415 ^^^^^^^^^^^^^^^^^^^
2416
2417 .. _v4l2-mpeg-cx2341x-video-spatial-filter-mode:
2418
2419 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_spatial_filter_mode)``
2420     Sets the Spatial Filter mode (default ``MANUAL``). Possible values
2421     are:
2422
2423
2424
2425 .. flat-table::
2426     :header-rows:  0
2427     :stub-columns: 0
2428
2429
2430     -  .. row 1
2431
2432        -  ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL``
2433
2434        -  Choose the filter manually
2435
2436     -  .. row 2
2437
2438        -  ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO``
2439
2440        -  Choose the filter automatically
2441
2442
2443
2444 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
2445     The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
2446     is 0.)
2447
2448 .. _luma-spatial-filter-type:
2449
2450 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type)``
2451     Select the algorithm to use for the Luma Spatial Filter (default
2452     ``1D_HOR``). Possible values:
2453
2454
2455
2456 .. flat-table::
2457     :header-rows:  0
2458     :stub-columns: 0
2459
2460
2461     -  .. row 1
2462
2463        -  ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
2464
2465        -  No filter
2466
2467     -  .. row 2
2468
2469        -  ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR``
2470
2471        -  One-dimensional horizontal
2472
2473     -  .. row 3
2474
2475        -  ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT``
2476
2477        -  One-dimensional vertical
2478
2479     -  .. row 4
2480
2481        -  ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE``
2482
2483        -  Two-dimensional separable
2484
2485     -  .. row 5
2486
2487        -  ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE``
2488
2489        -  Two-dimensional symmetrical non-separable
2490
2491
2492
2493 .. _chroma-spatial-filter-type:
2494
2495 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type)``
2496     Select the algorithm for the Chroma Spatial Filter (default
2497     ``1D_HOR``). Possible values are:
2498
2499
2500
2501 .. flat-table::
2502     :header-rows:  0
2503     :stub-columns: 0
2504
2505
2506     -  .. row 1
2507
2508        -  ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
2509
2510        -  No filter
2511
2512     -  .. row 2
2513
2514        -  ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
2515
2516        -  One-dimensional horizontal
2517
2518
2519
2520 .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode:
2521
2522 ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_temporal_filter_mode)``
2523     Sets the Temporal Filter mode (default ``MANUAL``). Possible values
2524     are:
2525
2526
2527
2528 .. flat-table::
2529     :header-rows:  0
2530     :stub-columns: 0
2531
2532
2533     -  .. row 1
2534
2535        -  ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL``
2536
2537        -  Choose the filter manually
2538
2539     -  .. row 2
2540
2541        -  ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO``
2542
2543        -  Choose the filter automatically
2544
2545
2546
2547 ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))``
2548     The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default
2549     is 8 for full-scale capturing and 0 for scaled capturing.)
2550
2551 .. _v4l2-mpeg-cx2341x-video-median-filter-type:
2552
2553 ``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_median_filter_type)``
2554     Median Filter Type (default ``OFF``). Possible values are:
2555
2556
2557
2558 .. flat-table::
2559     :header-rows:  0
2560     :stub-columns: 0
2561
2562
2563     -  .. row 1
2564
2565        -  ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
2566
2567        -  No filter
2568
2569     -  .. row 2
2570
2571        -  ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
2572
2573        -  Horizontal filter
2574
2575     -  .. row 3
2576
2577        -  ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
2578
2579        -  Vertical filter
2580
2581     -  .. row 4
2582
2583        -  ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
2584
2585        -  Horizontal and vertical filter
2586
2587     -  .. row 5
2588
2589        -  ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
2590
2591        -  Diagonal filter
2592
2593
2594
2595 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
2596     Threshold above which the luminance median filter is enabled
2597     (default 0)
2598
2599 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
2600     Threshold below which the luminance median filter is enabled
2601     (default 255)
2602
2603 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
2604     Threshold above which the chroma median filter is enabled (default
2605     0)
2606
2607 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
2608     Threshold below which the chroma median filter is enabled (default
2609     255)
2610
2611 ``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)``
2612     The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into
2613     the stream between every four video frames. The packet size is 2048
2614     bytes, including the packet_start_code_prefix and stream_id
2615     fields. The stream_id is 0xBF (private stream 2). The payload
2616     consists of 0x00 bytes, to be filled in by the application. 0 = do
2617     not insert, 1 = insert packets.
2618
2619
2620 VPX Control Reference
2621 ---------------------
2622
2623 The VPX controls include controls for encoding parameters of VPx video
2624 codec.
2625
2626
2627 .. _vpx-control-id:
2628
2629 VPX Control IDs
2630 ^^^^^^^^^^^^^^^
2631
2632 .. _v4l2-vpx-num-partitions:
2633
2634 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS (enum v4l2_vp8_num_partitions)``
2635     The number of token partitions to use in VP8 encoder. Possible
2636     values are:
2637
2638
2639
2640 .. flat-table::
2641     :header-rows:  0
2642     :stub-columns: 0
2643
2644
2645     -  .. row 1
2646
2647        -  ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION``
2648
2649        -  1 coefficient partition
2650
2651     -  .. row 2
2652
2653        -  ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS``
2654
2655        -  2 coefficient partitions
2656
2657     -  .. row 3
2658
2659        -  ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS``
2660
2661        -  4 coefficient partitions
2662
2663     -  .. row 4
2664
2665        -  ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS``
2666
2667        -  8 coefficient partitions
2668
2669
2670
2671 ``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
2672     Setting this prevents intra 4x4 mode in the intra mode decision.
2673
2674 .. _v4l2-vpx-num-ref-frames:
2675
2676 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES (enum v4l2_vp8_num_ref_frames)``
2677     The number of reference pictures for encoding P frames. Possible
2678     values are:
2679
2680
2681
2682 .. flat-table::
2683     :header-rows:  0
2684     :stub-columns: 0
2685
2686
2687     -  .. row 1
2688
2689        -  ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME``
2690
2691        -  Last encoded frame will be searched
2692
2693     -  .. row 2
2694
2695        -  ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME``
2696
2697        -  Two frames will be searched among the last encoded frame, the
2698           golden frame and the alternate reference (altref) frame. The
2699           encoder implementation will decide which two are chosen.
2700
2701     -  .. row 3
2702
2703        -  ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME``
2704
2705        -  The last encoded frame, the golden frame and the altref frame will
2706           be searched.
2707
2708
2709
2710 ``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)``
2711     Indicates the loop filter level. The adjustment of the loop filter
2712     level is done via a delta value against a baseline loop filter
2713     value.
2714
2715 ``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)``
2716     This parameter affects the loop filter. Anything above zero weakens
2717     the deblocking effect on the loop filter.
2718
2719 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)``
2720     Sets the refresh period for the golden frame. The period is defined
2721     in number of frames. For a value of 'n', every nth frame starting
2722     from the first key frame will be taken as a golden frame. For eg.
2723     for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden
2724     frame refresh period is set as 4, the frames 0, 4, 8 etc will be
2725     taken as the golden frames as frame 0 is always a key frame.
2726
2727 .. _v4l2-vpx-golden-frame-sel:
2728
2729 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL (enum v4l2_vp8_golden_frame_sel)``
2730     Selects the golden frame for encoding. Possible values are:
2731
2732
2733
2734 .. flat-table::
2735     :header-rows:  0
2736     :stub-columns: 0
2737
2738
2739     -  .. row 1
2740
2741        -  ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV``
2742
2743        -  Use the (n-2)th frame as a golden frame, current frame index being
2744           'n'.
2745
2746     -  .. row 2
2747
2748        -  ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD``
2749
2750        -  Use the previous specific frame indicated by
2751           V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a
2752           golden frame.
2753
2754
2755
2756 ``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
2757     Minimum quantization parameter for VP8.
2758
2759 ``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
2760     Maximum quantization parameter for VP8.
2761
2762 ``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
2763     Quantization parameter for an I frame for VP8.
2764
2765 ``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
2766     Quantization parameter for a P frame for VP8.
2767
2768 ``V4L2_CID_MPEG_VIDEO_VPX_PROFILE (integer)``
2769     Select the desired profile for VPx encoder. Acceptable values are 0,
2770     1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.
2771
2772
2773 .. _camera-controls:
2774
2775 Camera Control Reference
2776 ========================
2777
2778 The Camera class includes controls for mechanical (or equivalent
2779 digital) features of a device such as controllable lenses or sensors.
2780
2781
2782 .. _camera-control-id:
2783
2784 Camera Control IDs
2785 ------------------
2786
2787 ``V4L2_CID_CAMERA_CLASS (class)``
2788     The Camera class descriptor. Calling
2789     :ref:`VIDIOC_QUERYCTRL` for this control will
2790     return a description of this control class.
2791
2792 .. _v4l2-exposure-auto-type:
2793
2794 ``V4L2_CID_EXPOSURE_AUTO (enum v4l2_exposure_auto_type)``
2795     Enables automatic adjustments of the exposure time and/or iris
2796     aperture. The effect of manual changes of the exposure time or iris
2797     aperture while these features are enabled is undefined, drivers
2798     should ignore such requests. Possible values are:
2799
2800
2801
2802 .. flat-table::
2803     :header-rows:  0
2804     :stub-columns: 0
2805
2806
2807     -  .. row 1
2808
2809        -  ``V4L2_EXPOSURE_AUTO``
2810
2811        -  Automatic exposure time, automatic iris aperture.
2812
2813     -  .. row 2
2814
2815        -  ``V4L2_EXPOSURE_MANUAL``
2816
2817        -  Manual exposure time, manual iris.
2818
2819     -  .. row 3
2820
2821        -  ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
2822
2823        -  Manual exposure time, auto iris.
2824
2825     -  .. row 4
2826
2827        -  ``V4L2_EXPOSURE_APERTURE_PRIORITY``
2828
2829        -  Auto exposure time, manual iris.
2830
2831
2832
2833 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
2834     Determines the exposure time of the camera sensor. The exposure time
2835     is limited by the frame interval. Drivers should interpret the
2836     values as 100 µs units, where the value 1 stands for 1/10000th of a
2837     second, 10000 for 1 second and 100000 for 10 seconds.
2838
2839 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
2840     When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
2841     ``APERTURE_PRIORITY``, this control determines if the device may
2842     dynamically vary the frame rate. By default this feature is disabled
2843     (0) and the frame rate must remain constant.
2844
2845 ``V4L2_CID_EXPOSURE_BIAS (integer menu)``
2846     Determines the automatic exposure compensation, it is effective only
2847     when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
2848     ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
2849     terms of EV, drivers should interpret the values as 0.001 EV units,
2850     where the value 1000 stands for +1 EV.
2851
2852     Increasing the exposure compensation value is equivalent to
2853     decreasing the exposure value (EV) and will increase the amount of
2854     light at the image sensor. The camera performs the exposure
2855     compensation by adjusting absolute exposure time and/or aperture.
2856
2857 .. _v4l2-exposure-metering:
2858
2859 ``V4L2_CID_EXPOSURE_METERING (enum v4l2_exposure_metering)``
2860     Determines how the camera measures the amount of light available for
2861     the frame exposure. Possible values are:
2862
2863
2864
2865 .. flat-table::
2866     :header-rows:  0
2867     :stub-columns: 0
2868
2869
2870     -  .. row 1
2871
2872        -  ``V4L2_EXPOSURE_METERING_AVERAGE``
2873
2874        -  Use the light information coming from the entire frame and average
2875           giving no weighting to any particular portion of the metered area.
2876
2877     -  .. row 2
2878
2879        -  ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
2880
2881        -  Average the light information coming from the entire frame giving
2882           priority to the center of the metered area.
2883
2884     -  .. row 3
2885
2886        -  ``V4L2_EXPOSURE_METERING_SPOT``
2887
2888        -  Measure only very small area at the center of the frame.
2889
2890     -  .. row 4
2891
2892        -  ``V4L2_EXPOSURE_METERING_MATRIX``
2893
2894        -  A multi-zone metering. The light intensity is measured in several
2895           points of the frame and the results are combined. The algorithm of
2896           the zones selection and their significance in calculating the
2897           final value is device dependent.
2898
2899
2900
2901 ``V4L2_CID_PAN_RELATIVE (integer)``
2902     This control turns the camera horizontally by the specified amount.
2903     The unit is undefined. A positive value moves the camera to the
2904     right (clockwise when viewed from above), a negative value to the
2905     left. A value of zero does not cause motion. This is a write-only
2906     control.
2907
2908 ``V4L2_CID_TILT_RELATIVE (integer)``
2909     This control turns the camera vertically by the specified amount.
2910     The unit is undefined. A positive value moves the camera up, a
2911     negative value down. A value of zero does not cause motion. This is
2912     a write-only control.
2913
2914 ``V4L2_CID_PAN_RESET (button)``
2915     When this control is set, the camera moves horizontally to the
2916     default position.
2917
2918 ``V4L2_CID_TILT_RESET (button)``
2919     When this control is set, the camera moves vertically to the default
2920     position.
2921
2922 ``V4L2_CID_PAN_ABSOLUTE (integer)``
2923     This control turns the camera horizontally to the specified
2924     position. Positive values move the camera to the right (clockwise
2925     when viewed from above), negative values to the left. Drivers should
2926     interpret the values as arc seconds, with valid values between -180
2927     * 3600 and +180 * 3600 inclusive.
2928
2929 ``V4L2_CID_TILT_ABSOLUTE (integer)``
2930     This control turns the camera vertically to the specified position.
2931     Positive values move the camera up, negative values down. Drivers
2932     should interpret the values as arc seconds, with valid values
2933     between -180 * 3600 and +180 * 3600 inclusive.
2934
2935 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
2936     This control sets the focal point of the camera to the specified
2937     position. The unit is undefined. Positive values set the focus
2938     closer to the camera, negative values towards infinity.
2939
2940 ``V4L2_CID_FOCUS_RELATIVE (integer)``
2941     This control moves the focal point of the camera by the specified
2942     amount. The unit is undefined. Positive values move the focus closer
2943     to the camera, negative values towards infinity. This is a
2944     write-only control.
2945
2946 ``V4L2_CID_FOCUS_AUTO (boolean)``
2947     Enables continuous automatic focus adjustments. The effect of manual
2948     focus adjustments while this feature is enabled is undefined,
2949     drivers should ignore such requests.
2950
2951 ``V4L2_CID_AUTO_FOCUS_START (button)``
2952     Starts single auto focus process. The effect of setting this control
2953     when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
2954     drivers should ignore such requests.
2955
2956 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
2957     Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
2958     control. It is effective only when the continuous autofocus is
2959     disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
2960     ``FALSE`` (0).
2961
2962 .. _v4l2-auto-focus-status:
2963
2964 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
2965     The automatic focus status. This is a read-only control.
2966
2967     Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
2968     control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
2969     control value.
2970
2971
2972
2973 .. flat-table::
2974     :header-rows:  0
2975     :stub-columns: 0
2976
2977
2978     -  .. row 1
2979
2980        -  ``V4L2_AUTO_FOCUS_STATUS_IDLE``
2981
2982        -  Automatic focus is not active.
2983
2984     -  .. row 2
2985
2986        -  ``V4L2_AUTO_FOCUS_STATUS_BUSY``
2987
2988        -  Automatic focusing is in progress.
2989
2990     -  .. row 3
2991
2992        -  ``V4L2_AUTO_FOCUS_STATUS_REACHED``
2993
2994        -  Focus has been reached.
2995
2996     -  .. row 4
2997
2998        -  ``V4L2_AUTO_FOCUS_STATUS_FAILED``
2999
3000        -  Automatic focus has failed, the driver will not transition from
3001           this state until another action is performed by an application.
3002
3003
3004
3005 .. _v4l2-auto-focus-range:
3006
3007 ``V4L2_CID_AUTO_FOCUS_RANGE (enum v4l2_auto_focus_range)``
3008     Determines auto focus distance range for which lens may be adjusted.
3009
3010
3011
3012 .. flat-table::
3013     :header-rows:  0
3014     :stub-columns: 0
3015
3016
3017     -  .. row 1
3018
3019        -  ``V4L2_AUTO_FOCUS_RANGE_AUTO``
3020
3021        -  The camera automatically selects the focus range.
3022
3023     -  .. row 2
3024
3025        -  ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
3026
3027        -  Normal distance range, limited for best automatic focus
3028           performance.
3029
3030     -  .. row 3
3031
3032        -  ``V4L2_AUTO_FOCUS_RANGE_MACRO``
3033
3034        -  Macro (close-up) auto focus. The camera will use its minimum
3035           possible distance for auto focus.
3036
3037     -  .. row 4
3038
3039        -  ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
3040
3041        -  The lens is set to focus on an object at infinite distance.
3042
3043
3044
3045 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
3046     Specify the objective lens focal length as an absolute value. The
3047     zoom unit is driver-specific and its value should be a positive
3048     integer.
3049
3050 ``V4L2_CID_ZOOM_RELATIVE (integer)``
3051     Specify the objective lens focal length relatively to the current
3052     value. Positive values move the zoom lens group towards the
3053     telephoto direction, negative values towards the wide-angle
3054     direction. The zoom unit is driver-specific. This is a write-only
3055     control.
3056
3057 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
3058     Move the objective lens group at the specified speed until it
3059     reaches physical device limits or until an explicit request to stop
3060     the movement. A positive value moves the zoom lens group towards the
3061     telephoto direction. A value of zero stops the zoom lens group
3062     movement. A negative value moves the zoom lens group towards the
3063     wide-angle direction. The zoom speed unit is driver-specific.
3064
3065 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
3066     This control sets the camera's aperture to the specified value. The
3067     unit is undefined. Larger values open the iris wider, smaller values
3068     close it.
3069
3070 ``V4L2_CID_IRIS_RELATIVE (integer)``
3071     This control modifies the camera's aperture by the specified amount.
3072     The unit is undefined. Positive values open the iris one step
3073     further, negative values close it one step further. This is a
3074     write-only control.
3075
3076 ``V4L2_CID_PRIVACY (boolean)``
3077     Prevent video from being acquired by the camera. When this control
3078     is set to ``TRUE`` (1), no image can be captured by the camera.
3079     Common means to enforce privacy are mechanical obturation of the
3080     sensor and firmware image processing, but the device is not
3081     restricted to these methods. Devices that implement the privacy
3082     control must support read access and may support write access.
3083
3084 ``V4L2_CID_BAND_STOP_FILTER (integer)``
3085     Switch the band-stop filter of a camera sensor on or off, or specify
3086     its strength. Such band-stop filters can be used, for example, to
3087     filter out the fluorescent light component.
3088
3089 .. _v4l2-auto-n-preset-white-balance:
3090
3091 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE (enum v4l2_auto_n_preset_white_balance)``
3092     Sets white balance to automatic, manual or a preset. The presets
3093     determine color temperature of the light as a hint to the camera for
3094     white balance adjustments resulting in most accurate color
3095     representation. The following white balance presets are listed in
3096     order of increasing color temperature.
3097
3098
3099
3100 .. flat-table::
3101     :header-rows:  0
3102     :stub-columns: 0
3103
3104
3105     -  .. row 1
3106
3107        -  ``V4L2_WHITE_BALANCE_MANUAL``
3108
3109        -  Manual white balance.
3110
3111     -  .. row 2
3112
3113        -  ``V4L2_WHITE_BALANCE_AUTO``
3114
3115        -  Automatic white balance adjustments.
3116
3117     -  .. row 3
3118
3119        -  ``V4L2_WHITE_BALANCE_INCANDESCENT``
3120
3121        -  White balance setting for incandescent (tungsten) lighting. It
3122           generally cools down the colors and corresponds approximately to
3123           2500...3500 K color temperature range.
3124
3125     -  .. row 4
3126
3127        -  ``V4L2_WHITE_BALANCE_FLUORESCENT``
3128
3129        -  White balance preset for fluorescent lighting. It corresponds
3130           approximately to 4000...5000 K color temperature.
3131
3132     -  .. row 5
3133
3134        -  ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
3135
3136        -  With this setting the camera will compensate for fluorescent H
3137           lighting.
3138
3139     -  .. row 6
3140
3141        -  ``V4L2_WHITE_BALANCE_HORIZON``
3142
3143        -  White balance setting for horizon daylight. It corresponds
3144           approximately to 5000 K color temperature.
3145
3146     -  .. row 7
3147
3148        -  ``V4L2_WHITE_BALANCE_DAYLIGHT``
3149
3150        -  White balance preset for daylight (with clear sky). It corresponds
3151           approximately to 5000...6500 K color temperature.
3152
3153     -  .. row 8
3154
3155        -  ``V4L2_WHITE_BALANCE_FLASH``
3156
3157        -  With this setting the camera will compensate for the flash light.
3158           It slightly warms up the colors and corresponds roughly to
3159           5000...5500 K color temperature.
3160
3161     -  .. row 9
3162
3163        -  ``V4L2_WHITE_BALANCE_CLOUDY``
3164
3165        -  White balance preset for moderately overcast sky. This option
3166           corresponds approximately to 6500...8000 K color temperature
3167           range.
3168
3169     -  .. row 10
3170
3171        -  ``V4L2_WHITE_BALANCE_SHADE``
3172
3173        -  White balance preset for shade or heavily overcast sky. It
3174           corresponds approximately to 9000...10000 K color temperature.
3175
3176
3177
3178 .. _v4l2-wide-dynamic-range:
3179
3180 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
3181     Enables or disables the camera's wide dynamic range feature. This
3182     feature allows to obtain clear images in situations where intensity
3183     of the illumination varies significantly throughout the scene, i.e.
3184     there are simultaneously very dark and very bright areas. It is most
3185     commonly realized in cameras by combining two subsequent frames with
3186     different exposure times.  [#f1]_
3187
3188 .. _v4l2-image-stabilization:
3189
3190 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
3191     Enables or disables image stabilization.
3192
3193 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
3194     Determines ISO equivalent of an image sensor indicating the sensor's
3195     sensitivity to light. The numbers are expressed in arithmetic scale,
3196     as per :ref:`iso12232` standard, where doubling the sensor
3197     sensitivity is represented by doubling the numerical ISO value.
3198     Applications should interpret the values as standard ISO values
3199     multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
3200     Drivers will usually support only a subset of standard ISO values.
3201     The effect of setting this control while the
3202     ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
3203     than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
3204     should ignore such requests.
3205
3206 .. _v4l2-iso-sensitivity-auto-type:
3207
3208 ``V4L2_CID_ISO_SENSITIVITY_AUTO (enum v4l2_iso_sensitivity_type)``
3209     Enables or disables automatic ISO sensitivity adjustments.
3210
3211
3212
3213 .. flat-table::
3214     :header-rows:  0
3215     :stub-columns: 0
3216
3217
3218     -  .. row 1
3219
3220        -  ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
3221
3222        -  Manual ISO sensitivity.
3223
3224     -  .. row 2
3225
3226        -  ``V4L2_CID_ISO_SENSITIVITY_AUTO``
3227
3228        -  Automatic ISO sensitivity adjustments.
3229
3230
3231
3232 .. _v4l2-scene-mode:
3233
3234 ``V4L2_CID_SCENE_MODE (enum v4l2_scene_mode)``
3235     This control allows to select scene programs as the camera automatic
3236     modes optimized for common shooting scenes. Within these modes the
3237     camera determines best exposure, aperture, focusing, light metering,
3238     white balance and equivalent sensitivity. The controls of those
3239     parameters are influenced by the scene mode control. An exact
3240     behavior in each mode is subject to the camera specification.
3241
3242     When the scene mode feature is not used, this control should be set
3243     to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
3244     controls are accessible. The following scene programs are defined:
3245
3246
3247
3248 .. flat-table::
3249     :header-rows:  0
3250     :stub-columns: 0
3251
3252
3253     -  .. row 1
3254
3255        -  ``V4L2_SCENE_MODE_NONE``
3256
3257        -  The scene mode feature is disabled.
3258
3259     -  .. row 2
3260
3261        -  ``V4L2_SCENE_MODE_BACKLIGHT``
3262
3263        -  Backlight. Compensates for dark shadows when light is coming from
3264           behind a subject, also by automatically turning on the flash.
3265
3266     -  .. row 3
3267
3268        -  ``V4L2_SCENE_MODE_BEACH_SNOW``
3269
3270        -  Beach and snow. This mode compensates for all-white or bright
3271           scenes, which tend to look gray and low contrast, when camera's
3272           automatic exposure is based on an average scene brightness. To
3273           compensate, this mode automatically slightly overexposes the
3274           frames. The white balance may also be adjusted to compensate for
3275           the fact that reflected snow looks bluish rather than white.
3276
3277     -  .. row 4
3278
3279        -  ``V4L2_SCENE_MODE_CANDLELIGHT``
3280
3281        -  Candle light. The camera generally raises the ISO sensitivity and
3282           lowers the shutter speed. This mode compensates for relatively
3283           close subject in the scene. The flash is disabled in order to
3284           preserve the ambiance of the light.
3285
3286     -  .. row 5
3287
3288        -  ``V4L2_SCENE_MODE_DAWN_DUSK``
3289
3290        -  Dawn and dusk. Preserves the colors seen in low natural light
3291           before dusk and after down. The camera may turn off the flash, and
3292           automatically focus at infinity. It will usually boost saturation
3293           and lower the shutter speed.
3294
3295     -  .. row 6
3296
3297        -  ``V4L2_SCENE_MODE_FALL_COLORS``
3298
3299        -  Fall colors. Increases saturation and adjusts white balance for
3300           color enhancement. Pictures of autumn leaves get saturated reds
3301           and yellows.
3302
3303     -  .. row 7
3304
3305        -  ``V4L2_SCENE_MODE_FIREWORKS``
3306
3307        -  Fireworks. Long exposure times are used to capture the expanding
3308           burst of light from a firework. The camera may invoke image
3309           stabilization.
3310
3311     -  .. row 8
3312
3313        -  ``V4L2_SCENE_MODE_LANDSCAPE``
3314
3315        -  Landscape. The camera may choose a small aperture to provide deep
3316           depth of field and long exposure duration to help capture detail
3317           in dim light conditions. The focus is fixed at infinity. Suitable
3318           for distant and wide scenery.
3319
3320     -  .. row 9
3321
3322        -  ``V4L2_SCENE_MODE_NIGHT``
3323
3324        -  Night, also known as Night Landscape. Designed for low light
3325           conditions, it preserves detail in the dark areas without blowing
3326           out bright objects. The camera generally sets itself to a
3327           medium-to-high ISO sensitivity, with a relatively long exposure
3328           time, and turns flash off. As such, there will be increased image
3329           noise and the possibility of blurred image.
3330
3331     -  .. row 10
3332
3333        -  ``V4L2_SCENE_MODE_PARTY_INDOOR``
3334
3335        -  Party and indoor. Designed to capture indoor scenes that are lit
3336           by indoor background lighting as well as the flash. The camera
3337           usually increases ISO sensitivity, and adjusts exposure for the
3338           low light conditions.
3339
3340     -  .. row 11
3341
3342        -  ``V4L2_SCENE_MODE_PORTRAIT``
3343
3344        -  Portrait. The camera adjusts the aperture so that the depth of
3345           field is reduced, which helps to isolate the subject against a
3346           smooth background. Most cameras recognize the presence of faces in
3347           the scene and focus on them. The color hue is adjusted to enhance
3348           skin tones. The intensity of the flash is often reduced.
3349
3350     -  .. row 12
3351
3352        -  ``V4L2_SCENE_MODE_SPORTS``
3353
3354        -  Sports. Significantly increases ISO and uses a fast shutter speed
3355           to freeze motion of rapidly-moving subjects. Increased image noise
3356           may be seen in this mode.
3357
3358     -  .. row 13
3359
3360        -  ``V4L2_SCENE_MODE_SUNSET``
3361
3362        -  Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
3363           up the saturation.
3364
3365     -  .. row 14
3366
3367        -  ``V4L2_SCENE_MODE_TEXT``
3368
3369        -  Text. It applies extra contrast and sharpness, it is typically a
3370           black-and-white mode optimized for readability. Automatic focus
3371           may be switched to close-up mode and this setting may also involve
3372           some lens-distortion correction.
3373
3374
3375
3376 ``V4L2_CID_3A_LOCK (bitmask)``
3377     This control locks or unlocks the automatic focus, exposure and
3378     white balance. The automatic adjustments can be paused independently
3379     by setting the corresponding lock bit to 1. The camera then retains
3380     the settings until the lock bit is cleared. The following lock bits
3381     are defined:
3382
3383     When a given algorithm is not enabled, drivers should ignore
3384     requests to lock it and should return no error. An example might be
3385     an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
3386     ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
3387     value of this control may be changed by exposure, white balance or
3388     focus controls.
3389
3390
3391
3392 .. flat-table::
3393     :header-rows:  0
3394     :stub-columns: 0
3395
3396
3397     -  .. row 1
3398
3399        -  ``V4L2_LOCK_EXPOSURE``
3400
3401        -  Automatic exposure adjustments lock.
3402
3403     -  .. row 2
3404
3405        -  ``V4L2_LOCK_WHITE_BALANCE``
3406
3407        -  Automatic white balance adjustments lock.
3408
3409     -  .. row 3
3410
3411        -  ``V4L2_LOCK_FOCUS``
3412
3413        -  Automatic focus lock.
3414
3415
3416
3417 ``V4L2_CID_PAN_SPEED (integer)``
3418     This control turns the camera horizontally at the specific speed.
3419     The unit is undefined. A positive value moves the camera to the
3420     right (clockwise when viewed from above), a negative value to the
3421     left. A value of zero stops the motion if one is in progress and has
3422     no effect otherwise.
3423
3424 ``V4L2_CID_TILT_SPEED (integer)``
3425     This control turns the camera vertically at the specified speed. The
3426     unit is undefined. A positive value moves the camera up, a negative
3427     value down. A value of zero stops the motion if one is in progress
3428     and has no effect otherwise.
3429
3430
3431 .. _fm-tx-controls:
3432
3433 FM Transmitter Control Reference
3434 ================================
3435
3436 The FM Transmitter (FM_TX) class includes controls for common features
3437 of FM transmissions capable devices. Currently this class includes
3438 parameters for audio compression, pilot tone generation, audio deviation
3439 limiter, RDS transmission and tuning power features.
3440
3441
3442 .. _fm-tx-control-id:
3443
3444 FM_TX Control IDs
3445 -----------------
3446
3447 ``V4L2_CID_FM_TX_CLASS (class)``
3448     The FM_TX class descriptor. Calling
3449     :ref:`VIDIOC_QUERYCTRL` for this control will
3450     return a description of this control class.
3451
3452 ``V4L2_CID_RDS_TX_DEVIATION (integer)``
3453     Configures RDS signal frequency deviation level in Hz. The range and
3454     step are driver-specific.
3455
3456 ``V4L2_CID_RDS_TX_PI (integer)``
3457     Sets the RDS Programme Identification field for transmission.
3458
3459 ``V4L2_CID_RDS_TX_PTY (integer)``
3460     Sets the RDS Programme Type field for transmission. This encodes up
3461     to 31 pre-defined programme types.
3462
3463 ``V4L2_CID_RDS_TX_PS_NAME (string)``
3464     Sets the Programme Service name (PS_NAME) for transmission. It is
3465     intended for static display on a receiver. It is the primary aid to
3466     listeners in programme service identification and selection. In
3467     Annex E of :ref:`iec62106`, the RDS specification, there is a full
3468     description of the correct character encoding for Programme Service
3469     name strings. Also from RDS specification, PS is usually a single
3470     eight character text. However, it is also possible to find receivers
3471     which can scroll strings sized as 8 x N characters. So, this control
3472     must be configured with steps of 8 characters. The result is it must
3473     always contain a string with size multiple of 8.
3474
3475 ``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
3476     Sets the Radio Text info for transmission. It is a textual
3477     description of what is being broadcasted. RDS Radio Text can be
3478     applied when broadcaster wishes to transmit longer PS names,
3479     programme-related information or any other text. In these cases,
3480     RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
3481     The encoding for Radio Text strings is also fully described in Annex
3482     E of :ref:`iec62106`. The length of Radio Text strings depends on
3483     which RDS Block is being used to transmit it, either 32 (2A block)
3484     or 64 (2B block). However, it is also possible to find receivers
3485     which can scroll strings sized as 32 x N or 64 x N characters. So,
3486     this control must be configured with steps of 32 or 64 characters.
3487     The result is it must always contain a string with size multiple of
3488     32 or 64.
3489
3490 ``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
3491     Sets the Mono/Stereo bit of the Decoder Identification code. If set,
3492     then the audio was recorded as stereo.
3493
3494 ``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
3495     Sets the
3496     `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
3497     bit of the Decoder Identification code. If set, then the audio was
3498     recorded using an artificial head.
3499
3500 ``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
3501     Sets the Compressed bit of the Decoder Identification code. If set,
3502     then the audio is compressed.
3503
3504 ``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
3505     Sets the Dynamic PTY bit of the Decoder Identification code. If set,
3506     then the PTY code is dynamically switched.
3507
3508 ``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
3509     If set, then a traffic announcement is in progress.
3510
3511 ``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
3512     If set, then the tuned programme carries traffic announcements.
3513
3514 ``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
3515     If set, then this channel broadcasts music. If cleared, then it
3516     broadcasts speech. If the transmitter doesn't make this distinction,
3517     then it should be set.
3518
3519 ``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
3520     If set, then transmit alternate frequencies.
3521
3522 ``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
3523     The alternate frequencies in kHz units. The RDS standard allows for
3524     up to 25 frequencies to be defined. Drivers may support fewer
3525     frequencies so check the array size.
3526
3527 ``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
3528     Enables or disables the audio deviation limiter feature. The limiter
3529     is useful when trying to maximize the audio volume, minimize
3530     receiver-generated distortion and prevent overmodulation.
3531
3532 ``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
3533     Sets the audio deviation limiter feature release time. Unit is in
3534     useconds. Step and range are driver-specific.
3535
3536 ``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
3537     Configures audio frequency deviation level in Hz. The range and step
3538     are driver-specific.
3539
3540 ``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
3541     Enables or disables the audio compression feature. This feature
3542     amplifies signals below the threshold by a fixed gain and compresses
3543     audio signals above the threshold by the ratio of Threshold/(Gain +
3544     Threshold).
3545
3546 ``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
3547     Sets the gain for audio compression feature. It is a dB value. The
3548     range and step are driver-specific.
3549
3550 ``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
3551     Sets the threshold level for audio compression freature. It is a dB
3552     value. The range and step are driver-specific.
3553
3554 ``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
3555     Sets the attack time for audio compression feature. It is a useconds
3556     value. The range and step are driver-specific.
3557
3558 ``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
3559     Sets the release time for audio compression feature. It is a
3560     useconds value. The range and step are driver-specific.
3561
3562 ``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
3563     Enables or disables the pilot tone generation feature.
3564
3565 ``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
3566     Configures pilot tone frequency deviation level. Unit is in Hz. The
3567     range and step are driver-specific.
3568
3569 ``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
3570     Configures pilot tone frequency value. Unit is in Hz. The range and
3571     step are driver-specific.
3572
3573 ``V4L2_CID_TUNE_PREEMPHASIS (enum v4l2_preemphasis)``
3574     Configures the pre-emphasis value for broadcasting. A pre-emphasis
3575     filter is applied to the broadcast to accentuate the high audio
3576     frequencies. Depending on the region, a time constant of either 50
3577     or 75 useconds is used. The enum v4l2_preemphasis defines possible
3578     values for pre-emphasis. Here they are:
3579
3580
3581
3582 .. flat-table::
3583     :header-rows:  0
3584     :stub-columns: 0
3585
3586
3587     -  .. row 1
3588
3589        -  ``V4L2_PREEMPHASIS_DISABLED``
3590
3591        -  No pre-emphasis is applied.
3592
3593     -  .. row 2
3594
3595        -  ``V4L2_PREEMPHASIS_50_uS``
3596
3597        -  A pre-emphasis of 50 uS is used.
3598
3599     -  .. row 3
3600
3601        -  ``V4L2_PREEMPHASIS_75_uS``
3602
3603        -  A pre-emphasis of 75 uS is used.
3604
3605
3606
3607 ``V4L2_CID_TUNE_POWER_LEVEL (integer)``
3608     Sets the output power level for signal transmission. Unit is in
3609     dBuV. Range and step are driver-specific.
3610
3611 ``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
3612     This selects the value of antenna tuning capacitor manually or
3613     automatically if set to zero. Unit, range and step are
3614     driver-specific.
3615
3616 For more details about RDS specification, refer to :ref:`iec62106`
3617 document, from CENELEC.
3618
3619
3620 .. _flash-controls:
3621
3622 Flash Control Reference
3623 =======================
3624
3625 The V4L2 flash controls are intended to provide generic access to flash
3626 controller devices. Flash controller devices are typically used in
3627 digital cameras.
3628
3629 The interface can support both LED and xenon flash devices. As of
3630 writing this, there is no xenon flash driver using this interface.
3631
3632
3633 .. _flash-controls-use-cases:
3634
3635 Supported use cases
3636 -------------------
3637
3638
3639 Unsynchronised LED flash (software strobe)
3640 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3641
3642 Unsynchronised LED flash is controlled directly by the host as the
3643 sensor. The flash must be enabled by the host before the exposure of the
3644 image starts and disabled once it ends. The host is fully responsible
3645 for the timing of the flash.
3646
3647 Example of such device: Nokia N900.
3648
3649
3650 Synchronised LED flash (hardware strobe)
3651 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3652
3653 The synchronised LED flash is pre-programmed by the host (power and
3654 timeout) but controlled by the sensor through a strobe signal from the
3655 sensor to the flash.
3656
3657 The sensor controls the flash duration and timing. This information
3658 typically must be made available to the sensor.
3659
3660
3661 LED flash as torch
3662 ^^^^^^^^^^^^^^^^^^
3663
3664 LED flash may be used as torch in conjunction with another use case
3665 involving camera or individually.
3666
3667
3668 .. _flash-control-id:
3669
3670 Flash Control IDs
3671 """""""""""""""""
3672
3673 ``V4L2_CID_FLASH_CLASS (class)``
3674     The FLASH class descriptor.
3675
3676 ``V4L2_CID_FLASH_LED_MODE (menu)``
3677     Defines the mode of the flash LED, the high-power white LED attached
3678     to the flash controller. Setting this control may not be possible in
3679     presence of some faults. See V4L2_CID_FLASH_FAULT.
3680
3681
3682
3683 .. flat-table::
3684     :header-rows:  0
3685     :stub-columns: 0
3686
3687
3688     -  .. row 1
3689
3690        -  ``V4L2_FLASH_LED_MODE_NONE``
3691
3692        -  Off.
3693
3694     -  .. row 2
3695
3696        -  ``V4L2_FLASH_LED_MODE_FLASH``
3697
3698        -  Flash mode.
3699
3700     -  .. row 3
3701
3702        -  ``V4L2_FLASH_LED_MODE_TORCH``
3703
3704        -  Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
3705
3706
3707
3708 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
3709     Defines the source of the flash LED strobe.
3710
3711
3712
3713 .. flat-table::
3714     :header-rows:  0
3715     :stub-columns: 0
3716
3717
3718     -  .. row 1
3719
3720        -  ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
3721
3722        -  The flash strobe is triggered by using the
3723           V4L2_CID_FLASH_STROBE control.
3724
3725     -  .. row 2
3726
3727        -  ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
3728
3729        -  The flash strobe is triggered by an external source. Typically
3730           this is a sensor, which makes it possible to synchronises the
3731           flash strobe start to exposure start.
3732
3733
3734
3735 ``V4L2_CID_FLASH_STROBE (button)``
3736     Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
3737     V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
3738     is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
3739     control may not be possible in presence of some faults. See
3740     V4L2_CID_FLASH_FAULT.
3741
3742 ``V4L2_CID_FLASH_STROBE_STOP (button)``
3743     Stop flash strobe immediately.
3744
3745 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
3746     Strobe status: whether the flash is strobing at the moment or not.
3747     This is a read-only control.
3748
3749 ``V4L2_CID_FLASH_TIMEOUT (integer)``
3750     Hardware timeout for flash. The flash strobe is stopped after this
3751     period of time has passed from the start of the strobe.
3752
3753 ``V4L2_CID_FLASH_INTENSITY (integer)``
3754     Intensity of the flash strobe when the flash LED is in flash mode
3755     (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
3756     if possible.
3757
3758 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
3759     Intensity of the flash LED in torch mode
3760     (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
3761     if possible. Setting this control may not be possible in presence of
3762     some faults. See V4L2_CID_FLASH_FAULT.
3763
3764 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
3765     Intensity of the indicator LED. The indicator LED may be fully
3766     independent of the flash LED. The unit should be microamps (uA) if
3767     possible.
3768
3769 ``V4L2_CID_FLASH_FAULT (bitmask)``
3770     Faults related to the flash. The faults tell about specific problems
3771     in the flash chip itself or the LEDs attached to it. Faults may
3772     prevent further use of some of the flash controls. In particular,
3773     V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
3774     if the fault affects the flash LED. Exactly which faults have such
3775     an effect is chip dependent. Reading the faults resets the control
3776     and returns the chip to a usable state if possible.
3777
3778
3779
3780 .. flat-table::
3781     :header-rows:  0
3782     :stub-columns: 0
3783
3784
3785     -  .. row 1
3786
3787        -  ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
3788
3789        -  Flash controller voltage to the flash LED has exceeded the limit
3790           specific to the flash controller.
3791
3792     -  .. row 2
3793
3794        -  ``V4L2_FLASH_FAULT_TIMEOUT``
3795
3796        -  The flash strobe was still on when the timeout set by the user ---
3797           V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
3798           controllers may set this in all such conditions.
3799
3800     -  .. row 3
3801
3802        -  ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
3803
3804        -  The flash controller has overheated.
3805
3806     -  .. row 4
3807
3808        -  ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
3809
3810        -  The short circuit protection of the flash controller has been
3811           triggered.
3812
3813     -  .. row 5
3814
3815        -  ``V4L2_FLASH_FAULT_OVER_CURRENT``
3816
3817        -  Current in the LED power supply has exceeded the limit specific to
3818           the flash controller.
3819
3820     -  .. row 6
3821
3822        -  ``V4L2_FLASH_FAULT_INDICATOR``
3823
3824        -  The flash controller has detected a short or open circuit
3825           condition on the indicator LED.
3826
3827     -  .. row 7
3828
3829        -  ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
3830
3831        -  Flash controller voltage to the flash LED has been below the
3832           minimum limit specific to the flash controller.
3833
3834     -  .. row 8
3835
3836        -  ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
3837
3838        -  The input voltage of the flash controller is below the limit under
3839           which strobing the flash at full current will not be possible.The
3840           condition persists until this flag is no longer set.
3841
3842     -  .. row 9
3843
3844        -  ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
3845
3846        -  The temperature of the LED has exceeded its allowed upper limit.
3847
3848
3849
3850 ``V4L2_CID_FLASH_CHARGE (boolean)``
3851     Enable or disable charging of the xenon flash capacitor.
3852
3853 ``V4L2_CID_FLASH_READY (boolean)``
3854     Is the flash ready to strobe? Xenon flashes require their capacitors
3855     charged before strobing. LED flashes often require a cooldown period
3856     after strobe during which another strobe will not be possible. This
3857     is a read-only control.
3858
3859
3860 .. _jpeg-controls:
3861
3862 JPEG Control Reference
3863 ======================
3864
3865 The JPEG class includes controls for common features of JPEG encoders
3866 and decoders. Currently it includes features for codecs implementing
3867 progressive baseline DCT compression process with Huffman entrophy
3868 coding.
3869
3870
3871 .. _jpeg-control-id:
3872
3873 JPEG Control IDs
3874 ----------------
3875
3876 ``V4L2_CID_JPEG_CLASS (class)``
3877     The JPEG class descriptor. Calling
3878     :ref:`VIDIOC_QUERYCTRL` for this control will
3879     return a description of this control class.
3880
3881 ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
3882     The chroma subsampling factors describe how each component of an
3883     input image is sampled, in respect to maximum sample rate in each
3884     spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
3885     details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
3886     how Cb and Cr components are downsampled after coverting an input
3887     image from RGB to Y'CbCr color space.
3888
3889
3890
3891 .. flat-table::
3892     :header-rows:  0
3893     :stub-columns: 0
3894
3895
3896     -  .. row 1
3897
3898        -  ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
3899
3900        -  No chroma subsampling, each pixel has Y, Cr and Cb values.
3901
3902     -  .. row 2
3903
3904        -  ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
3905
3906        -  Horizontally subsample Cr, Cb components by a factor of 2.
3907
3908     -  .. row 3
3909
3910        -  ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
3911
3912        -  Subsample Cr, Cb components horizontally and vertically by 2.
3913
3914     -  .. row 4
3915
3916        -  ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
3917
3918        -  Horizontally subsample Cr, Cb components by a factor of 4.
3919
3920     -  .. row 5
3921
3922        -  ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
3923
3924        -  Subsample Cr, Cb components horizontally by 4 and vertically by 2.
3925
3926     -  .. row 6
3927
3928        -  ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
3929
3930        -  Use only luminance component.
3931
3932
3933
3934 ``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
3935     The restart interval determines an interval of inserting RSTm
3936     markers (m = 0..7). The purpose of these markers is to additionally
3937     reinitialize the encoder process, in order to process blocks of an
3938     image independently. For the lossy compression processes the restart
3939     interval unit is MCU (Minimum Coded Unit) and its value is contained
3940     in DRI (Define Restart Interval) marker. If
3941     ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
3942     markers will not be inserted.
3943
3944 .. _jpeg-quality-control:
3945
3946 ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
3947     ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
3948     between image quality and size. It provides simpler method for
3949     applications to control image quality, without a need for direct
3950     reconfiguration of luminance and chrominance quantization tables. In
3951     cases where a driver uses quantization tables configured directly by
3952     an application, using interfaces defined elsewhere,
3953     ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
3954     driver to 0.
3955
3956     The value range of this control is driver-specific. Only positive,
3957     non-zero values are meaningful. The recommended range is 1 - 100,
3958     where larger values correspond to better image quality.
3959
3960 .. _jpeg-active-marker-control:
3961
3962 ``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
3963     Specify which JPEG markers are included in compressed stream. This
3964     control is valid only for encoders.
3965
3966
3967
3968 .. flat-table::
3969     :header-rows:  0
3970     :stub-columns: 0
3971
3972
3973     -  .. row 1
3974
3975        -  ``V4L2_JPEG_ACTIVE_MARKER_APP0``
3976
3977        -  Application data segment APP\ :sub:`0`.
3978
3979     -  .. row 2
3980
3981        -  ``V4L2_JPEG_ACTIVE_MARKER_APP1``
3982
3983        -  Application data segment APP\ :sub:`1`.
3984
3985     -  .. row 3
3986
3987        -  ``V4L2_JPEG_ACTIVE_MARKER_COM``
3988
3989        -  Comment segment.
3990
3991     -  .. row 4
3992
3993        -  ``V4L2_JPEG_ACTIVE_MARKER_DQT``
3994
3995        -  Quantization tables segment.
3996
3997     -  .. row 5
3998
3999        -  ``V4L2_JPEG_ACTIVE_MARKER_DHT``
4000
4001        -  Huffman tables segment.
4002
4003
4004
4005 For more details about JPEG specification, refer to :ref:`itu-t81`,
4006 :ref:`jfif`, :ref:`w3c-jpeg-jfif`.
4007
4008
4009 .. _image-source-controls:
4010
4011 Image Source Control Reference
4012 ==============================
4013
4014 The Image Source control class is intended for low-level control of
4015 image source devices such as image sensors. The devices feature an
4016 analogue to digital converter and a bus transmitter to transmit the
4017 image data out of the device.
4018
4019
4020 .. _image-source-control-id:
4021
4022 Image Source Control IDs
4023 ------------------------
4024
4025 ``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
4026     The IMAGE_SOURCE class descriptor.
4027
4028 ``V4L2_CID_VBLANK (integer)``
4029     Vertical blanking. The idle period after every frame during which no
4030     image data is produced. The unit of vertical blanking is a line.
4031     Every line has length of the image width plus horizontal blanking at
4032     the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
4033     same sub-device.
4034
4035 ``V4L2_CID_HBLANK (integer)``
4036     Horizontal blanking. The idle period after every line of image data
4037     during which no image data is produced. The unit of horizontal
4038     blanking is pixels.
4039
4040 ``V4L2_CID_ANALOGUE_GAIN (integer)``
4041     Analogue gain is gain affecting all colour components in the pixel
4042     matrix. The gain operation is performed in the analogue domain
4043     before A/D conversion.
4044
4045 ``V4L2_CID_TEST_PATTERN_RED (integer)``
4046     Test pattern red colour component.
4047
4048 ``V4L2_CID_TEST_PATTERN_GREENR (integer)``
4049     Test pattern green (next to red) colour component.
4050
4051 ``V4L2_CID_TEST_PATTERN_BLUE (integer)``
4052     Test pattern blue colour component.
4053
4054 ``V4L2_CID_TEST_PATTERN_GREENB (integer)``
4055     Test pattern green (next to blue) colour component.
4056
4057
4058 .. _image-process-controls:
4059
4060 Image Process Control Reference
4061 ===============================
4062
4063 The Image Process control class is intended for low-level control of
4064 image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
4065 controls in this class affect processing the image, and do not control
4066 capturing of it.
4067
4068
4069 .. _image-process-control-id:
4070
4071 Image Process Control IDs
4072 -------------------------
4073
4074 ``V4L2_CID_IMAGE_PROC_CLASS (class)``
4075     The IMAGE_PROC class descriptor.
4076
4077 ``V4L2_CID_LINK_FREQ (integer menu)``
4078     Data bus frequency. Together with the media bus pixel code, bus type
4079     (clock cycles per sample), the data bus frequency defines the pixel
4080     rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly
4081     elsewhere, if the device is not an image sensor). The frame rate can
4082     be calculated from the pixel clock, image width and height and
4083     horizontal and vertical blanking. While the pixel rate control may
4084     be defined elsewhere than in the subdev containing the pixel array,
4085     the frame rate cannot be obtained from that information. This is
4086     because only on the pixel array it can be assumed that the vertical
4087     and horizontal blanking information is exact: no other blanking is
4088     allowed in the pixel array. The selection of frame rate is performed
4089     by selecting the desired horizontal and vertical blanking. The unit
4090     of this control is Hz.
4091
4092 ``V4L2_CID_PIXEL_RATE (64-bit integer)``
4093     Pixel rate in the source pads of the subdev. This control is
4094     read-only and its unit is pixels / second.
4095
4096 ``V4L2_CID_TEST_PATTERN (menu)``
4097     Some capture/display/sensor devices have the capability to generate
4098     test pattern images. These hardware specific test patterns can be
4099     used to test if a device is working properly.
4100
4101
4102 .. _dv-controls:
4103
4104 Digital Video Control Reference
4105 ===============================
4106
4107 The Digital Video control class is intended to control receivers and
4108 transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
4109 `DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
4110 (Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
4111 (:ref:`dp`). These controls are generally expected to be private to
4112 the receiver or transmitter subdevice that implements them, so they are
4113 only exposed on the ``/dev/v4l-subdev*`` device node.
4114
4115 .. note::
4116
4117    Note that these devices can have multiple input or output pads which are
4118    hooked up to e.g. HDMI connectors. Even though the subdevice will
4119    receive or transmit video from/to only one of those pads, the other pads
4120    can still be active when it comes to EDID (Extended Display
4121    Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
4122    Content Protection System, :ref:`hdcp`) processing, allowing the
4123    device to do the fairly slow EDID/HDCP handling in advance. This allows
4124    for quick switching between connectors.
4125
4126 These pads appear in several of the controls in this section as
4127 bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
4128 1, etc. The maximum value of the control is the set of valid pads.
4129
4130
4131 .. _dv-control-id:
4132
4133 Digital Video Control IDs
4134 -------------------------
4135
4136 ``V4L2_CID_DV_CLASS (class)``
4137     The Digital Video class descriptor.
4138
4139 ``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
4140     Many connectors have a hotplug pin which is high if EDID information
4141     is available from the source. This control shows the state of the
4142     hotplug pin as seen by the transmitter. Each bit corresponds to an
4143     output pad on the transmitter. If an output pad does not have an
4144     associated hotplug pin, then the bit for that pad will be 0. This
4145     read-only control is applicable to DVI-D, HDMI and DisplayPort
4146     connectors.
4147
4148 ``V4L2_CID_DV_TX_RXSENSE (bitmask)``
4149     Rx Sense is the detection of pull-ups on the TMDS clock lines. This
4150     normally means that the sink has left/entered standby (i.e. the
4151     transmitter can sense that the receiver is ready to receive video).
4152     Each bit corresponds to an output pad on the transmitter. If an
4153     output pad does not have an associated Rx Sense, then the bit for
4154     that pad will be 0. This read-only control is applicable to DVI-D
4155     and HDMI devices.
4156
4157 ``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
4158     When the transmitter sees the hotplug signal from the receiver it
4159     will attempt to read the EDID. If set, then the transmitter has read
4160     at least the first block (= 128 bytes). Each bit corresponds to an
4161     output pad on the transmitter. If an output pad does not support
4162     EDIDs, then the bit for that pad will be 0. This read-only control
4163     is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
4164
4165 ``V4L2_CID_DV_TX_MODE (enum v4l2_dv_tx_mode)``
4166     HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
4167     mode (video + audio + auxiliary data). This control selects which
4168     mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
4169     This control is applicable to HDMI connectors.
4170
4171 ``V4L2_CID_DV_TX_RGB_RANGE (enum v4l2_dv_rgb_range)``
4172     Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
4173     follows the RGB quantization range specified in the standard for the
4174     video interface (ie. :ref:`cea861` for HDMI).
4175     V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
4176     standard to be compatible with sinks that have not implemented the
4177     standard correctly (unfortunately quite common for HDMI and DVI-D).
4178     Full range allows all possible values to be used whereas limited
4179     range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
4180     the number of bits per component. This control is applicable to VGA,
4181     DVI-A/D, HDMI and DisplayPort connectors.
4182
4183 ``V4L2_CID_DV_TX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
4184     Configures the IT Content Type of the transmitted video. This
4185     information is sent over HDMI and DisplayPort connectors as part of
4186     the AVI InfoFrame. The term 'IT Content' is used for content that
4187     originates from a computer as opposed to content from a TV broadcast
4188     or an analog source. The enum v4l2_dv_it_content_type defines
4189     the possible content types:
4190
4191
4192
4193 .. flat-table::
4194     :header-rows:  0
4195     :stub-columns: 0
4196
4197
4198     -  .. row 1
4199
4200        -  ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
4201
4202        -  Graphics content. Pixel data should be passed unfiltered and
4203           without analog reconstruction.
4204
4205     -  .. row 2
4206
4207        -  ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
4208
4209        -  Photo content. The content is derived from digital still pictures.
4210           The content should be passed through with minimal scaling and
4211           picture enhancements.
4212
4213     -  .. row 3
4214
4215        -  ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
4216
4217        -  Cinema content.
4218
4219     -  .. row 4
4220
4221        -  ``V4L2_DV_IT_CONTENT_TYPE_GAME``
4222
4223        -  Game content. Audio and video latency should be minimized.
4224
4225     -  .. row 5
4226
4227        -  ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
4228
4229        -  No IT Content information is available and the ITC bit in the AVI
4230           InfoFrame is set to 0.
4231
4232
4233
4234 ``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
4235     Detects whether the receiver receives power from the source (e.g.
4236     HDMI carries 5V on one of the pins). This is often used to power an
4237     eeprom which contains EDID information, such that the source can
4238     read the EDID even if the sink is in standby/power off. Each bit
4239     corresponds to an input pad on the transmitter. If an input pad
4240     cannot detect whether power is present, then the bit for that pad
4241     will be 0. This read-only control is applicable to DVI-D, HDMI and
4242     DisplayPort connectors.
4243
4244 ``V4L2_CID_DV_RX_RGB_RANGE (enum v4l2_dv_rgb_range)``
4245     Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
4246     follows the RGB quantization range specified in the standard for the
4247     video interface (ie. :ref:`cea861` for HDMI).
4248     V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
4249     standard to be compatible with sources that have not implemented the
4250     standard correctly (unfortunately quite common for HDMI and DVI-D).
4251     Full range allows all possible values to be used whereas limited
4252     range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
4253     the number of bits per component. This control is applicable to VGA,
4254     DVI-A/D, HDMI and DisplayPort connectors.
4255
4256 ``V4L2_CID_DV_RX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
4257     Reads the IT Content Type of the received video. This information is
4258     sent over HDMI and DisplayPort connectors as part of the AVI
4259     InfoFrame. The term 'IT Content' is used for content that originates
4260     from a computer as opposed to content from a TV broadcast or an
4261     analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
4262     available content types.
4263
4264
4265 .. _fm-rx-controls:
4266
4267 FM Receiver Control Reference
4268 =============================
4269
4270 The FM Receiver (FM_RX) class includes controls for common features of
4271 FM Reception capable devices.
4272
4273
4274 .. _fm-rx-control-id:
4275
4276 FM_RX Control IDs
4277 -----------------
4278
4279 ``V4L2_CID_FM_RX_CLASS (class)``
4280     The FM_RX class descriptor. Calling
4281     :ref:`VIDIOC_QUERYCTRL` for this control will
4282     return a description of this control class.
4283
4284 ``V4L2_CID_RDS_RECEPTION (boolean)``
4285     Enables/disables RDS reception by the radio tuner
4286
4287 ``V4L2_CID_RDS_RX_PTY (integer)``
4288     Gets RDS Programme Type field. This encodes up to 31 pre-defined
4289     programme types.
4290
4291 ``V4L2_CID_RDS_RX_PS_NAME (string)``
4292     Gets the Programme Service name (PS_NAME). It is intended for
4293     static display on a receiver. It is the primary aid to listeners in
4294     programme service identification and selection. In Annex E of
4295     :ref:`iec62106`, the RDS specification, there is a full
4296     description of the correct character encoding for Programme Service
4297     name strings. Also from RDS specification, PS is usually a single
4298     eight character text. However, it is also possible to find receivers
4299     which can scroll strings sized as 8 x N characters. So, this control
4300     must be configured with steps of 8 characters. The result is it must
4301     always contain a string with size multiple of 8.
4302
4303 ``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
4304     Gets the Radio Text info. It is a textual description of what is
4305     being broadcasted. RDS Radio Text can be applied when broadcaster
4306     wishes to transmit longer PS names, programme-related information or
4307     any other text. In these cases, RadioText can be used in addition to
4308     ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
4309     also fully described in Annex E of :ref:`iec62106`. The length of
4310     Radio Text strings depends on which RDS Block is being used to
4311     transmit it, either 32 (2A block) or 64 (2B block). However, it is
4312     also possible to find receivers which can scroll strings sized as 32
4313     x N or 64 x N characters. So, this control must be configured with
4314     steps of 32 or 64 characters. The result is it must always contain a
4315     string with size multiple of 32 or 64.
4316
4317 ``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
4318     If set, then a traffic announcement is in progress.
4319
4320 ``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
4321     If set, then the tuned programme carries traffic announcements.
4322
4323 ``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
4324     If set, then this channel broadcasts music. If cleared, then it
4325     broadcasts speech. If the transmitter doesn't make this distinction,
4326     then it will be set.
4327
4328 ``V4L2_CID_TUNE_DEEMPHASIS (enum v4l2_deemphasis)``
4329     Configures the de-emphasis value for reception. A de-emphasis filter
4330     is applied to the broadcast to accentuate the high audio
4331     frequencies. Depending on the region, a time constant of either 50
4332     or 75 useconds is used. The enum v4l2_deemphasis defines possible
4333     values for de-emphasis. Here they are:
4334
4335
4336
4337 .. flat-table::
4338     :header-rows:  0
4339     :stub-columns: 0
4340
4341
4342     -  .. row 1
4343
4344        -  ``V4L2_DEEMPHASIS_DISABLED``
4345
4346        -  No de-emphasis is applied.
4347
4348     -  .. row 2
4349
4350        -  ``V4L2_DEEMPHASIS_50_uS``
4351
4352        -  A de-emphasis of 50 uS is used.
4353
4354     -  .. row 3
4355
4356        -  ``V4L2_DEEMPHASIS_75_uS``
4357
4358        -  A de-emphasis of 75 uS is used.
4359
4360
4361
4362
4363 .. _detect-controls:
4364
4365 Detect Control Reference
4366 ========================
4367
4368 The Detect class includes controls for common features of various motion
4369 or object detection capable devices.
4370
4371
4372 .. _detect-control-id:
4373
4374 Detect Control IDs
4375 ------------------
4376
4377 ``V4L2_CID_DETECT_CLASS (class)``
4378     The Detect class descriptor. Calling
4379     :ref:`VIDIOC_QUERYCTRL` for this control will
4380     return a description of this control class.
4381
4382 ``V4L2_CID_DETECT_MD_MODE (menu)``
4383     Sets the motion detection mode.
4384
4385
4386
4387 .. flat-table::
4388     :header-rows:  0
4389     :stub-columns: 0
4390
4391
4392     -  .. row 1
4393
4394        -  ``V4L2_DETECT_MD_MODE_DISABLED``
4395
4396        -  Disable motion detection.
4397
4398     -  .. row 2
4399
4400        -  ``V4L2_DETECT_MD_MODE_GLOBAL``
4401
4402        -  Use a single motion detection threshold.
4403
4404     -  .. row 3
4405
4406        -  ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
4407
4408        -  The image is divided into a grid, each cell with its own motion
4409           detection threshold. These thresholds are set through the
4410           ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
4411
4412     -  .. row 4
4413
4414        -  ``V4L2_DETECT_MD_MODE_REGION_GRID``
4415
4416        -  The image is divided into a grid, each cell with its own region
4417           value that specifies which per-region motion detection thresholds
4418           should be used. Each region has its own thresholds. How these
4419           per-region thresholds are set up is driver-specific. The region
4420           values for the grid are set through the
4421           ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
4422
4423
4424
4425 ``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
4426     Sets the global motion detection threshold to be used with the
4427     ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
4428
4429 ``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
4430     Sets the motion detection thresholds for each cell in the grid. To
4431     be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
4432     detection mode. Matrix element (0, 0) represents the cell at the
4433     top-left of the grid.
4434
4435 ``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
4436     Sets the motion detection region value for each cell in the grid. To
4437     be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
4438     detection mode. Matrix element (0, 0) represents the cell at the
4439     top-left of the grid.
4440
4441
4442 .. _rf-tuner-controls:
4443
4444 RF Tuner Control Reference
4445 ==========================
4446
4447 The RF Tuner (RF_TUNER) class includes controls for common features of
4448 devices having RF tuner.
4449
4450 In this context, RF tuner is radio receiver circuit between antenna and
4451 demodulator. It receives radio frequency (RF) from the antenna and
4452 converts that received signal to lower intermediate frequency (IF) or
4453 baseband frequency (BB). Tuners that could do baseband output are often
4454 called Zero-IF tuners. Older tuners were typically simple PLL tuners
4455 inside a metal box, whilst newer ones are highly integrated chips
4456 without a metal box "silicon tuners". These controls are mostly
4457 applicable for new feature rich silicon tuners, just because older
4458 tuners does not have much adjustable features.
4459
4460 For more information about RF tuners see
4461 `Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
4462 and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
4463 from Wikipedia.
4464
4465
4466 .. _rf-tuner-control-id:
4467
4468 RF_TUNER Control IDs
4469 --------------------
4470
4471 ``V4L2_CID_RF_TUNER_CLASS (class)``
4472     The RF_TUNER class descriptor. Calling
4473     :ref:`VIDIOC_QUERYCTRL` for this control will
4474     return a description of this control class.
4475
4476 ``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
4477     Enables/disables tuner radio channel bandwidth configuration. In
4478     automatic mode bandwidth configuration is performed by the driver.
4479
4480 ``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
4481     Filter(s) on tuner signal path are used to filter signal according
4482     to receiving party needs. Driver configures filters to fulfill
4483     desired bandwidth requirement. Used when
4484     V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
4485     range and step are driver-specific.
4486
4487 ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
4488     Enables/disables LNA automatic gain control (AGC)
4489
4490 ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
4491     Enables/disables mixer automatic gain control (AGC)
4492
4493 ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
4494     Enables/disables IF automatic gain control (AGC)
4495
4496 ``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
4497     The RF amplifier is the very first amplifier on the receiver signal
4498     path, just right after the antenna input. The difference between the
4499     LNA gain and the RF gain in this document is that the LNA gain is
4500     integrated in the tuner chip while the RF gain is a separate chip.
4501     There may be both RF and LNA gain controls in the same device. The
4502     range and step are driver-specific.
4503
4504 ``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
4505     LNA (low noise amplifier) gain is first gain stage on the RF tuner
4506     signal path. It is located very close to tuner antenna input. Used
4507     when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
4508     ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
4509     differs from the each others. The range and step are
4510     driver-specific.
4511
4512 ``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
4513     Mixer gain is second gain stage on the RF tuner signal path. It is
4514     located inside mixer block, where RF signal is down-converted by the
4515     mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
4516     The range and step are driver-specific.
4517
4518 ``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
4519     IF gain is last gain stage on the RF tuner signal path. It is
4520     located on output of RF tuner. It controls signal level of
4521     intermediate frequency output or baseband output. Used when
4522     ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
4523     are driver-specific.
4524
4525 ``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
4526     Is synthesizer PLL locked? RF tuner is receiving given frequency
4527     when that control is set. This is a read-only control.
4528
4529 .. [#f1]
4530    This control may be changed to a menu control in the future, if more
4531    options are required.