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.7cm}|p{3.5cm}|p{10.1cm}|
  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 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
  91
  92 .. c:type:: v4l2_captureparm
  93
  94 .. flat-table:: struct v4l2_captureparm
  95     :header-rows:  0
  96     :stub-columns: 0
  97     :widths:       1 1 2
  98
  99     * - __u32
 100       - ``capability``
 101       - See :ref:`parm-caps`.
 102     * - __u32
 103       - ``capturemode``
 104       - Set by drivers and applications, see :ref:`parm-flags`.
 105     * - struct :c:type:`v4l2_fract`
 106       - ``timeperframe``
 107       - This is the desired period between successive frames captured by
 108         the driver, in seconds.
 109     * - :cspan:`2`
 110
 111         This will configure the speed at which the video source (e.g. a sensor)
 112         generates video frames. If the speed is fixed, then the driver may
 113         choose to skip or repeat frames in order to achieve the requested
 114         frame rate.
 115
 116         For stateful encoders (see :ref:`encoder`) this represents the
 117         frame interval that is typically embedded in the encoded video stream.
 118
 119         Applications store here the desired frame period, drivers return
 120         the actual frame period.
 121
 122         Changing the video standard (also implicitly by switching
 123         the video input) may reset this parameter to the nominal frame
 124         period. To reset manually applications can just set this field to
 125         zero.
 126
 127         Drivers support this function only when they set the
 128         ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
 129     * - __u32
 130       - ``extendedmode``
 131       - Custom (driver specific) streaming parameters. When unused,
 132         applications and drivers must set this field to zero. Applications
 133         using this field should check the driver name and version, see
 134         :ref:`querycap`.
 135     * - __u32
 136       - ``readbuffers``
 137       - Applications set this field to the desired number of buffers used
 138         internally by the driver in :c:func:`read()` mode.
 139         Drivers return the actual number of buffers. When an application
 140         requests zero buffers, drivers should just return the current
 141         setting rather than the minimum or an error code. For details see
 142         :ref:`rw`.
 143     * - __u32
 144       - ``reserved``\ [4]
 145       - Reserved for future extensions. Drivers and applications must set
 146         the array to zero.
 147
 148
 149 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
 150
 151 .. c:type:: v4l2_outputparm
 152
 153 .. flat-table:: struct v4l2_outputparm
 154     :header-rows:  0
 155     :stub-columns: 0
 156     :widths:       1 1 2
 157
 158     * - __u32
 159       - ``capability``
 160       - See :ref:`parm-caps`.
 161     * - __u32
 162       - ``outputmode``
 163       - Set by drivers and applications, see :ref:`parm-flags`.
 164     * - struct :c:type:`v4l2_fract`
 165       - ``timeperframe``
 166       - This is the desired period between successive frames output by the
 167         driver, in seconds.
 168     * - :cspan:`2`
 169
 170         The field is intended to repeat frames on the driver side in
 171         :c:func:`write()` mode (in streaming mode timestamps
 172         can be used to throttle the output), saving I/O bandwidth.
 173
 174         For stateful encoders (see :ref:`encoder`) this represents the
 175         frame interval that is typically embedded in the encoded video stream
 176         and it provides a hint to the encoder of the speed at which raw
 177         frames are queued up to the encoder.
 178
 179         Applications store here the desired frame period, drivers return
 180         the actual frame period.
 181
 182         Changing the video standard (also implicitly by switching
 183         the video output) may reset this parameter to the nominal frame
 184         period. To reset manually applications can just set this field to
 185         zero.
 186
 187         Drivers support this function only when they set the
 188         ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
 189     * - __u32
 190       - ``extendedmode``
 191       - Custom (driver specific) streaming parameters. When unused,
 192         applications and drivers must set this field to zero. Applications
 193         using this field should check the driver name and version, see
 194         :ref:`querycap`.
 195     * - __u32
 196       - ``writebuffers``
 197       - Applications set this field to the desired number of buffers used
 198         internally by the driver in :c:func:`write()` mode. Drivers
 199         return the actual number of buffers. When an application requests
 200         zero buffers, drivers should just return the current setting
 201         rather than the minimum or an error code. For details see
 202         :ref:`rw`.
 203     * - __u32
 204       - ``reserved``\ [4]
 205       - Reserved for future extensions. Drivers and applications must set
 206         the array to zero.
 207
 208
 209 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
 210
 211 .. _parm-caps:
 212
 213 .. flat-table:: Streaming Parameters Capabilities
 214     :header-rows:  0
 215     :stub-columns: 0
 216     :widths:       3 1 4
 217
 218     * - ``V4L2_CAP_TIMEPERFRAME``
 219       - 0x1000
 220       - The frame period can be modified by setting the ``timeperframe``
 221         field.
 222
 223
 224 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
 225
 226 .. _parm-flags:
 227
 228 .. flat-table:: Capture Parameters Flags
 229     :header-rows:  0
 230     :stub-columns: 0
 231     :widths:       3 1 4
 232
 233     * - ``V4L2_MODE_HIGHQUALITY``
 234       - 0x0001
 235       - High quality imaging mode. High quality mode is intended for still
 236         imaging applications. The idea is to get the best possible image
 237         quality that the hardware can deliver. It is not defined how the
 238         driver writer may achieve that; it will depend on the hardware and
 239         the ingenuity of the driver writer. High quality mode is a
 240         different mode from the regular motion video capture modes. In
 241         high quality mode:
 242
 243         -  The driver may be able to capture higher resolutions than for
 244            motion capture.
 245
 246         -  The driver may support fewer pixel formats than motion capture
 247            (eg; true color).
 248
 249         -  The driver may capture and arithmetically combine multiple
 250            successive fields or frames to remove color edge artifacts and
 251            reduce the noise in the video data.
 252
 253         -  The driver may capture images in slices like a scanner in order
 254            to handle larger format images than would otherwise be
 255            possible.
 256
 257         -  An image capture operation may be significantly slower than
 258            motion capture.
 259
 260         -  Moving objects in the image might have excessive motion blur.
 261
 262         -  Capture might only work through the :c:func:`read()` call.
 263
 264 Return Value
 265 ============
 266
 267 On success 0 is returned, on error -1 and the ``errno`` variable is set
 268 appropriately. The generic error codes are described at the
 269 :ref:`Generic Error Codes <gen-errors>` chapter.