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