Documentation/media/uapi/v4l/vidioc-g-parm.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_PARM:
   4
   5 **********************************
   6 ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
   7 **********************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_G_PARM, VIDIOC_S_PARM
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 The current video standard determines a nominal number of frames per
  37 second. If less than this number of frames is to be captured or output,
  38 applications can request frame skipping or duplicating on the driver
  39 side. This is especially useful when using the :ref:`read() <func-read>` or
  40 :ref:`write() <func-write>`, which are not augmented by timestamps or sequence
  41 counters, and to avoid unnecessary data copying.
  42
  43 Further these ioctls can be used to determine the number of buffers used
  44 internally by a driver in read/write mode. For implications see the
  45 section discussing the :ref:`read() <func-read>` function.
  46
  47 To get and set the streaming parameters applications call the
  48 :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
  49 pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a
  50 union holding separate parameters for input and output devices.
  51
  52
  53 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
  54
  55 .. _v4l2-streamparm:
  56
  57 .. flat-table:: struct v4l2_streamparm
  58     :header-rows:  0
  59     :stub-columns: 0
  60     :widths:       1 1 1 2
  61
  62
  63     -  .. row 1
  64
  65        -  __u32
  66
  67        -  ``type``
  68
  69        -
  70        -  The buffer (stream) type, same as struct
  71           :ref:`v4l2_format <v4l2-format>` ``type``, set by the
  72           application. See :ref:`v4l2-buf-type`
  73
  74     -  .. row 2
  75
  76        -  union
  77
  78        -  ``parm``
  79
  80        -
  81        -
  82
  83     -  .. row 3
  84
  85        -
  86        -  struct :ref:`v4l2_captureparm <v4l2-captureparm>`
  87
  88        -  ``capture``
  89
  90        -  Parameters for capture devices, used when ``type`` is
  91           ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
  92
  93     -  .. row 4
  94
  95        -
  96        -  struct :ref:`v4l2_outputparm <v4l2-outputparm>`
  97
  98        -  ``output``
  99
 100        -  Parameters for output devices, used when ``type`` is
 101           ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
 102
 103     -  .. row 5
 104
 105        -
 106        -  __u8
 107
 108        -  ``raw_data``\ [200]
 109
 110        -  A place holder for future extensions.
 111
 112
 113
 114 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 115
 116 .. _v4l2-captureparm:
 117
 118 .. flat-table:: struct v4l2_captureparm
 119     :header-rows:  0
 120     :stub-columns: 0
 121     :widths:       1 1 2
 122
 123
 124     -  .. row 1
 125
 126        -  __u32
 127
 128        -  ``capability``
 129
 130        -  See :ref:`parm-caps`.
 131
 132     -  .. row 2
 133
 134        -  __u32
 135
 136        -  ``capturemode``
 137
 138        -  Set by drivers and applications, see :ref:`parm-flags`.
 139
 140     -  .. row 3
 141
 142        -  struct :ref:`v4l2_fract <v4l2-fract>`
 143
 144        -  ``timeperframe``
 145
 146        -  This is the desired period between successive frames captured by
 147           the driver, in seconds. The field is intended to skip frames on
 148           the driver side, saving I/O bandwidth.
 149
 150           Applications store here the desired frame period, drivers return
 151           the actual frame period, which must be greater or equal to the
 152           nominal frame period determined by the current video standard
 153           (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
 154           field). Changing the video standard (also implicitly by switching
 155           the video input) may reset this parameter to the nominal frame
 156           period. To reset manually applications can just set this field to
 157           zero.
 158
 159           Drivers support this function only when they set the
 160           ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
 161
 162     -  .. row 4
 163
 164        -  __u32
 165
 166        -  ``extendedmode``
 167
 168        -  Custom (driver specific) streaming parameters. When unused,
 169           applications and drivers must set this field to zero. Applications
 170           using this field should check the driver name and version, see
 171           :ref:`querycap`.
 172
 173     -  .. row 5
 174
 175        -  __u32
 176
 177        -  ``readbuffers``
 178
 179        -  Applications set this field to the desired number of buffers used
 180           internally by the driver in :ref:`read() <func-read>` mode.
 181           Drivers return the actual number of buffers. When an application
 182           requests zero buffers, drivers should just return the current
 183           setting rather than the minimum or an error code. For details see
 184           :ref:`rw`.
 185
 186     -  .. row 6
 187
 188        -  __u32
 189
 190        -  ``reserved``\ [4]
 191
 192        -  Reserved for future extensions. Drivers and applications must set
 193           the array to zero.
 194
 195
 196
 197 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 198
 199 .. _v4l2-outputparm:
 200
 201 .. flat-table:: struct v4l2_outputparm
 202     :header-rows:  0
 203     :stub-columns: 0
 204     :widths:       1 1 2
 205
 206
 207     -  .. row 1
 208
 209        -  __u32
 210
 211        -  ``capability``
 212
 213        -  See :ref:`parm-caps`.
 214
 215     -  .. row 2
 216
 217        -  __u32
 218
 219        -  ``outputmode``
 220
 221        -  Set by drivers and applications, see :ref:`parm-flags`.
 222
 223     -  .. row 3
 224
 225        -  struct :ref:`v4l2_fract <v4l2-fract>`
 226
 227        -  ``timeperframe``
 228
 229        -  This is the desired period between successive frames output by the
 230           driver, in seconds.
 231
 232     -  .. row 4
 233
 234        -  :cspan:`2`
 235
 236           The field is intended to repeat frames on the driver side in
 237           :ref:`write() <func-write>` mode (in streaming mode timestamps
 238           can be used to throttle the output), saving I/O bandwidth.
 239
 240           Applications store here the desired frame period, drivers return
 241           the actual frame period, which must be greater or equal to the
 242           nominal frame period determined by the current video standard
 243           (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
 244           field). Changing the video standard (also implicitly by switching
 245           the video output) may reset this parameter to the nominal frame
 246           period. To reset manually applications can just set this field to
 247           zero.
 248
 249           Drivers support this function only when they set the
 250           ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
 251
 252     -  .. row 5
 253
 254        -  __u32
 255
 256        -  ``extendedmode``
 257
 258        -  Custom (driver specific) streaming parameters. When unused,
 259           applications and drivers must set this field to zero. Applications
 260           using this field should check the driver name and version, see
 261           :ref:`querycap`.
 262
 263     -  .. row 6
 264
 265        -  __u32
 266
 267        -  ``writebuffers``
 268
 269        -  Applications set this field to the desired number of buffers used
 270           internally by the driver in :ref:`write() <func-write>` mode. Drivers
 271           return the actual number of buffers. When an application requests
 272           zero buffers, drivers should just return the current setting
 273           rather than the minimum or an error code. For details see
 274           :ref:`rw`.
 275
 276     -  .. row 7
 277
 278        -  __u32
 279
 280        -  ``reserved``\ [4]
 281
 282        -  Reserved for future extensions. Drivers and applications must set
 283           the array to zero.
 284
 285
 286
 287 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 288
 289 .. _parm-caps:
 290
 291 .. flat-table:: Streaming Parameters Capabilites
 292     :header-rows:  0
 293     :stub-columns: 0
 294     :widths:       3 1 4
 295
 296
 297     -  .. row 1
 298
 299        -  ``V4L2_CAP_TIMEPERFRAME``
 300
 301        -  0x1000
 302
 303        -  The frame skipping/repeating controlled by the ``timeperframe``
 304           field is supported.
 305
 306
 307
 308 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 309
 310 .. _parm-flags:
 311
 312 .. flat-table:: Capture Parameters Flags
 313     :header-rows:  0
 314     :stub-columns: 0
 315     :widths:       3 1 4
 316
 317
 318     -  .. row 1
 319
 320        -  ``V4L2_MODE_HIGHQUALITY``
 321
 322        -  0x0001
 323
 324        -  High quality imaging mode. High quality mode is intended for still
 325           imaging applications. The idea is to get the best possible image
 326           quality that the hardware can deliver. It is not defined how the
 327           driver writer may achieve that; it will depend on the hardware and
 328           the ingenuity of the driver writer. High quality mode is a
 329           different mode from the regular motion video capture modes. In
 330           high quality mode:
 331
 332           -  The driver may be able to capture higher resolutions than for
 333              motion capture.
 334
 335           -  The driver may support fewer pixel formats than motion capture
 336              (eg; true color).
 337
 338           -  The driver may capture and arithmetically combine multiple
 339              successive fields or frames to remove color edge artifacts and
 340              reduce the noise in the video data.
 341
 342           -  The driver may capture images in slices like a scanner in order
 343              to handle larger format images than would otherwise be
 344              possible.
 345
 346           -  An image capture operation may be significantly slower than
 347              motion capture.
 348
 349           -  Moving objects in the image might have excessive motion blur.
 350
 351           -  Capture might only work through the :ref:`read() <func-read>` call.
 352
 353
 354 Return Value
 355 ============
 356
 357 On success 0 is returned, on error -1 and the ``errno`` variable is set
 358 appropriately. The generic error codes are described at the
 359 :ref:`Generic Error Codes <gen-errors>` chapter.