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