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