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