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

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