| .. -*- coding: utf-8; mode: rst -*- |
| |
| .. _VIDIOC_G_PARM: |
| |
| ********************************** |
| ioctl VIDIOC_G_PARM, VIDIOC_S_PARM |
| ********************************** |
| |
| *man VIDIOC_G_PARM(2)* |
| |
| VIDIOC_S_PARM |
| Get or set streaming parameters |
| |
| |
| Synopsis |
| ======== |
| |
| .. c:function:: int ioctl( int fd, int request, v4l2_streamparm *argp ) |
| |
| Arguments |
| ========= |
| |
| ``fd`` |
| File descriptor returned by :ref:`open() <func-open>`. |
| |
| ``request`` |
| VIDIOC_G_PARM, VIDIOC_S_PARM |
| |
| ``argp`` |
| |
| |
| Description |
| =========== |
| |
| The current video standard determines a nominal number of frames per |
| second. If less than this number of frames is to be captured or output, |
| applications can request frame skipping or duplicating on the driver |
| side. This is especially useful when using the :c:func:`read()` or |
| :c:func:`write()`, which are not augmented by timestamps or sequence |
| counters, and to avoid unnecessary data copying. |
| |
| Further these ioctls can be used to determine the number of buffers used |
| internally by a driver in read/write mode. For implications see the |
| section discussing the :ref:`read() <func-read>` function. |
| |
| To get and set the streaming parameters applications call the |
| ``VIDIOC_G_PARM`` and ``VIDIOC_S_PARM`` ioctl, respectively. They take a |
| pointer to a struct :c:type:`struct v4l2_streamparm` which contains a |
| union holding separate parameters for input and output devices. |
| |
| |
| .. _v4l2-streamparm: |
| |
| .. flat-table:: struct v4l2_streamparm |
| :header-rows: 0 |
| :stub-columns: 0 |
| :widths: 1 1 1 2 |
| |
| |
| - .. row 1 |
| |
| - __u32 |
| |
| - ``type`` |
| |
| - |
| - The buffer (stream) type, same as struct |
| :ref:`v4l2_format <v4l2-format>` ``type``, set by the |
| application. See :ref:`v4l2-buf-type` |
| |
| - .. row 2 |
| |
| - union |
| |
| - ``parm`` |
| |
| - |
| - |
| |
| - .. row 3 |
| |
| - |
| - struct :ref:`v4l2_captureparm <v4l2-captureparm>` |
| |
| - ``capture`` |
| |
| - Parameters for capture devices, used when ``type`` is |
| ``V4L2_BUF_TYPE_VIDEO_CAPTURE``. |
| |
| - .. row 4 |
| |
| - |
| - struct :ref:`v4l2_outputparm <v4l2-outputparm>` |
| |
| - ``output`` |
| |
| - Parameters for output devices, used when ``type`` is |
| ``V4L2_BUF_TYPE_VIDEO_OUTPUT``. |
| |
| - .. row 5 |
| |
| - |
| - __u8 |
| |
| - ``raw_data``\ [200] |
| |
| - A place holder for future extensions. |
| |
| |
| |
| .. _v4l2-captureparm: |
| |
| .. flat-table:: struct v4l2_captureparm |
| :header-rows: 0 |
| :stub-columns: 0 |
| :widths: 1 1 2 |
| |
| |
| - .. row 1 |
| |
| - __u32 |
| |
| - ``capability`` |
| |
| - See :ref:`parm-caps`. |
| |
| - .. row 2 |
| |
| - __u32 |
| |
| - ``capturemode`` |
| |
| - Set by drivers and applications, see :ref:`parm-flags`. |
| |
| - .. row 3 |
| |
| - struct :ref:`v4l2_fract <v4l2-fract>` |
| |
| - ``timeperframe`` |
| |
| - This is the desired period between successive frames captured by |
| the driver, in seconds. The field is intended to skip frames on |
| the driver side, saving I/O bandwidth. |
| |
| Applications store here the desired frame period, drivers return |
| the actual frame period, which must be greater or equal to the |
| nominal frame period determined by the current video standard |
| (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod`` |
| field). Changing the video standard (also implicitly by switching |
| the video input) may reset this parameter to the nominal frame |
| period. To reset manually applications can just set this field to |
| zero. |
| |
| Drivers support this function only when they set the |
| ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. |
| |
| - .. row 4 |
| |
| - __u32 |
| |
| - ``extendedmode`` |
| |
| - Custom (driver specific) streaming parameters. When unused, |
| applications and drivers must set this field to zero. Applications |
| using this field should check the driver name and version, see |
| :ref:`querycap`. |
| |
| - .. row 5 |
| |
| - __u32 |
| |
| - ``readbuffers`` |
| |
| - Applications set this field to the desired number of buffers used |
| internally by the driver in :ref:`read() <func-read>` mode. |
| Drivers return the actual number of buffers. When an application |
| requests zero buffers, drivers should just return the current |
| setting rather than the minimum or an error code. For details see |
| :ref:`rw`. |
| |
| - .. row 6 |
| |
| - __u32 |
| |
| - ``reserved``\ [4] |
| |
| - Reserved for future extensions. Drivers and applications must set |
| the array to zero. |
| |
| |
| |
| .. _v4l2-outputparm: |
| |
| .. flat-table:: struct v4l2_outputparm |
| :header-rows: 0 |
| :stub-columns: 0 |
| :widths: 1 1 2 |
| |
| |
| - .. row 1 |
| |
| - __u32 |
| |
| - ``capability`` |
| |
| - See :ref:`parm-caps`. |
| |
| - .. row 2 |
| |
| - __u32 |
| |
| - ``outputmode`` |
| |
| - Set by drivers and applications, see :ref:`parm-flags`. |
| |
| - .. row 3 |
| |
| - struct :ref:`v4l2_fract <v4l2-fract>` |
| |
| - ``timeperframe`` |
| |
| - This is the desired period between successive frames output by the |
| driver, in seconds. |
| |
| - .. row 4 |
| |
| - :cspan:`2` |
| |
| The field is intended to repeat frames on the driver side in |
| :ref:`write() <func-write>` mode (in streaming mode timestamps |
| can be used to throttle the output), saving I/O bandwidth. |
| |
| Applications store here the desired frame period, drivers return |
| the actual frame period, which must be greater or equal to the |
| nominal frame period determined by the current video standard |
| (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod`` |
| field). Changing the video standard (also implicitly by switching |
| the video output) may reset this parameter to the nominal frame |
| period. To reset manually applications can just set this field to |
| zero. |
| |
| Drivers support this function only when they set the |
| ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. |
| |
| - .. row 5 |
| |
| - __u32 |
| |
| - ``extendedmode`` |
| |
| - Custom (driver specific) streaming parameters. When unused, |
| applications and drivers must set this field to zero. Applications |
| using this field should check the driver name and version, see |
| :ref:`querycap`. |
| |
| - .. row 6 |
| |
| - __u32 |
| |
| - ``writebuffers`` |
| |
| - Applications set this field to the desired number of buffers used |
| internally by the driver in :c:func:`write()` mode. Drivers |
| return the actual number of buffers. When an application requests |
| zero buffers, drivers should just return the current setting |
| rather than the minimum or an error code. For details see |
| :ref:`rw`. |
| |
| - .. row 7 |
| |
| - __u32 |
| |
| - ``reserved``\ [4] |
| |
| - Reserved for future extensions. Drivers and applications must set |
| the array to zero. |
| |
| |
| |
| .. _parm-caps: |
| |
| .. flat-table:: Streaming Parameters Capabilites |
| :header-rows: 0 |
| :stub-columns: 0 |
| :widths: 3 1 4 |
| |
| |
| - .. row 1 |
| |
| - ``V4L2_CAP_TIMEPERFRAME`` |
| |
| - 0x1000 |
| |
| - The frame skipping/repeating controlled by the ``timeperframe`` |
| field is supported. |
| |
| |
| |
| .. _parm-flags: |
| |
| .. flat-table:: Capture Parameters Flags |
| :header-rows: 0 |
| :stub-columns: 0 |
| :widths: 3 1 4 |
| |
| |
| - .. row 1 |
| |
| - ``V4L2_MODE_HIGHQUALITY`` |
| |
| - 0x0001 |
| |
| - High quality imaging mode. High quality mode is intended for still |
| imaging applications. The idea is to get the best possible image |
| quality that the hardware can deliver. It is not defined how the |
| driver writer may achieve that; it will depend on the hardware and |
| the ingenuity of the driver writer. High quality mode is a |
| different mode from the regular motion video capture modes. In |
| high quality mode: |
| |
| - The driver may be able to capture higher resolutions than for |
| motion capture. |
| |
| - The driver may support fewer pixel formats than motion capture |
| (eg; true color). |
| |
| - The driver may capture and arithmetically combine multiple |
| successive fields or frames to remove color edge artifacts and |
| reduce the noise in the video data. |
| |
| - The driver may capture images in slices like a scanner in order |
| to handle larger format images than would otherwise be |
| possible. |
| |
| - An image capture operation may be significantly slower than |
| motion capture. |
| |
| - Moving objects in the image might have excessive motion blur. |
| |
| - Capture might only work through the :c:func:`read()` call. |
| |
| |
| |
| Return Value |
| ============ |
| |
| On success 0 is returned, on error -1 and the ``errno`` variable is set |
| appropriately. The generic error codes are described at the |
| :ref:`Generic Error Codes <gen-errors>` chapter. |
| |
| |
| .. ------------------------------------------------------------------------------ |
| .. This file was automatically converted from DocBook-XML with the dbxml |
| .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| .. from the linux kernel, refer to: |
| .. |
| .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| .. ------------------------------------------------------------------------------ |