Documentation/userspace-api/media/v4l/vidioc-g-parm.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_G_PARM:
   5
   6 **********************************
   7 ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
   8 **********************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_G_PARM
  19
  20 ``int ioctl(int fd, VIDIOC_G_PARM, v4l2_streamparm *argp)``
  21
  22 .. c:macro:: VIDIOC_S_PARM
  23
  24 ``int ioctl(int fd, VIDIOC_S_PARM, v4l2_streamparm *argp)``
  25
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by :c:func:`open()`.
  31
  32 ``argp``
  33     Pointer to struct :c:type:`v4l2_streamparm`.
  34
  35 Description
  36 ===========
  37
  38 Applications can request a different frame interval. The capture or
  39 output device will be reconfigured to support the requested frame
  40 interval if possible. Optionally drivers may choose to skip or
  41 repeat frames to achieve the requested frame interval.
  42
  43 For stateful encoders (see :ref:`encoder`) this represents the
  44 frame interval that is typically embedded in the encoded video stream.
  45
  46 Changing the frame interval shall never change the format. Changing the
  47 format, on the other hand, may change the frame interval.
  48
  49 Further these ioctls can be used to determine the number of buffers used
  50 internally by a driver in read/write mode. For implications see the
  51 section discussing the :c:func:`read()` function.
  52
  53 To get and set the streaming parameters applications call the
  54 :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
  55 :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
  56 pointer to a struct :c:type:`v4l2_streamparm` which contains a
  57 union holding separate parameters for input and output devices.
  58
  59 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
  60
  61 .. c:type:: v4l2_streamparm
  62
  63 .. flat-table:: struct v4l2_streamparm
  64     :header-rows:  0
  65     :stub-columns: 0
  66     :widths:       1 1 2
  67
  68     * - __u32
  69       - ``type``
  70       - The buffer (stream) type, same as struct
  71         :c:type:`v4l2_format` ``type``, set by the
  72         application. See :c:type:`v4l2_buf_type`.
  73     * - union {
  74       - ``parm``
  75     * - struct :c:type:`v4l2_captureparm`
  76       - ``capture``
  77       - Parameters for capture devices, used when ``type`` is
  78         ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
  79         ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``.
  80     * - struct :c:type:`v4l2_outputparm`
  81       - ``output``
  82       - Parameters for output devices, used when ``type`` is
  83         ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
  84     * - __u8
  85       - ``raw_data``\ [200]
  86       - A place holder for future extensions.
  87     * - }
  88       -
  89
  90
  91 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  92
  93 .. c:type:: v4l2_captureparm
  94
  95 .. flat-table:: struct v4l2_captureparm
  96     :header-rows:  0
  97     :stub-columns: 0
  98     :widths:       1 1 2
  99
 100     * - __u32
 101       - ``capability``
 102       - See :ref:`parm-caps`.
 103     * - __u32
 104       - ``capturemode``
 105       - Set by drivers and applications, see :ref:`parm-flags`.
 106     * - struct :c:type:`v4l2_fract`
 107       - ``timeperframe``
 108       - This is the desired period between successive frames captured by
 109         the driver, in seconds.
 110     * - :cspan:`2`
 111
 112         This will configure the speed at which the video source (e.g. a sensor)
 113         generates video frames. If the speed is fixed, then the driver may
 114         choose to skip or repeat frames in order to achieve the requested
 115         frame rate.
 116
 117         For stateful encoders (see :ref:`encoder`) this represents the
 118         frame interval that is typically embedded in the encoded video stream.
 119
 120         Applications store here the desired frame period, drivers return
 121         the actual frame period.
 122
 123         Changing the video standard (also implicitly by switching
 124         the video input) may reset this parameter to the nominal frame
 125         period. To reset manually applications can just set this field to
 126         zero.
 127
 128         Drivers support this function only when they set the
 129         ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
 130     * - __u32
 131       - ``extendedmode``
 132       - Custom (driver specific) streaming parameters. When unused,
 133         applications and drivers must set this field to zero. Applications
 134         using this field should check the driver name and version, see
 135         :ref:`querycap`.
 136     * - __u32
 137       - ``readbuffers``
 138       - Applications set this field to the desired number of buffers used
 139         internally by the driver in :c:func:`read()` mode.
 140         Drivers return the actual number of buffers. When an application
 141         requests zero buffers, drivers should just return the current
 142         setting rather than the minimum or an error code. For details see
 143         :ref:`rw`.
 144     * - __u32
 145       - ``reserved``\ [4]
 146       - Reserved for future extensions. Drivers and applications must set
 147         the array to zero.
 148
 149
 150 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 151
 152 .. c:type:: v4l2_outputparm
 153
 154 .. flat-table:: struct v4l2_outputparm
 155     :header-rows:  0
 156     :stub-columns: 0
 157     :widths:       1 1 2
 158
 159     * - __u32
 160       - ``capability``
 161       - See :ref:`parm-caps`.
 162     * - __u32
 163       - ``outputmode``
 164       - Set by drivers and applications, see :ref:`parm-flags`.
 165     * - struct :c:type:`v4l2_fract`
 166       - ``timeperframe``
 167       - This is the desired period between successive frames output by the
 168         driver, in seconds.
 169     * - :cspan:`2`
 170
 171         The field is intended to repeat frames on the driver side in
 172         :c:func:`write()` mode (in streaming mode timestamps
 173         can be used to throttle the output), saving I/O bandwidth.
 174
 175         For stateful encoders (see :ref:`encoder`) this represents the
 176         frame interval that is typically embedded in the encoded video stream
 177         and it provides a hint to the encoder of the speed at which raw
 178         frames are queued up to the encoder.
 179
 180         Applications store here the desired frame period, drivers return
 181         the actual frame period.
 182
 183         Changing the video standard (also implicitly by switching
 184         the video output) may reset this parameter to the nominal frame
 185         period. To reset manually applications can just set this field to
 186         zero.
 187
 188         Drivers support this function only when they set the
 189         ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
 190     * - __u32
 191       - ``extendedmode``
 192       - Custom (driver specific) streaming parameters. When unused,
 193         applications and drivers must set this field to zero. Applications
 194         using this field should check the driver name and version, see
 195         :ref:`querycap`.
 196     * - __u32
 197       - ``writebuffers``
 198       - Applications set this field to the desired number of buffers used
 199         internally by the driver in :c:func:`write()` mode. Drivers
 200         return the actual number of buffers. When an application requests
 201         zero buffers, drivers should just return the current setting
 202         rather than the minimum or an error code. For details see
 203         :ref:`rw`.
 204     * - __u32
 205       - ``reserved``\ [4]
 206       - Reserved for future extensions. Drivers and applications must set
 207         the array to zero.
 208
 209
 210 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 211
 212 .. _parm-caps:
 213
 214 .. flat-table:: Streaming Parameters Capabilities
 215     :header-rows:  0
 216     :stub-columns: 0
 217     :widths:       3 1 4
 218
 219     * - ``V4L2_CAP_TIMEPERFRAME``
 220       - 0x1000
 221       - The frame period can be modified by setting the ``timeperframe``
 222         field.
 223
 224
 225 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 226
 227 .. _parm-flags:
 228
 229 .. flat-table:: Capture Parameters Flags
 230     :header-rows:  0
 231     :stub-columns: 0
 232     :widths:       3 1 4
 233
 234     * - ``V4L2_MODE_HIGHQUALITY``
 235       - 0x0001
 236       - High quality imaging mode. High quality mode is intended for still
 237         imaging applications. The idea is to get the best possible image
 238         quality that the hardware can deliver. It is not defined how the
 239         driver writer may achieve that; it will depend on the hardware and
 240         the ingenuity of the driver writer. High quality mode is a
 241         different mode from the regular motion video capture modes. In
 242         high quality mode:
 243
 244         -  The driver may be able to capture higher resolutions than for
 245            motion capture.
 246
 247         -  The driver may support fewer pixel formats than motion capture
 248            (eg; true color).
 249
 250         -  The driver may capture and arithmetically combine multiple
 251            successive fields or frames to remove color edge artifacts and
 252            reduce the noise in the video data.
 253
 254         -  The driver may capture images in slices like a scanner in order
 255            to handle larger format images than would otherwise be
 256            possible.
 257
 258         -  An image capture operation may be significantly slower than
 259            motion capture.
 260
 261         -  Moving objects in the image might have excessive motion blur.
 262
 263         -  Capture might only work through the :c:func:`read()` call.
 264
 265 Return Value
 266 ============
 267
 268 On success 0 is returned, on error -1 and the ``errno`` variable is set
 269 appropriately. The generic error codes are described at the
 270 :ref:`Generic Error Codes <gen-errors>` chapter.