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

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