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