diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-g-parm.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-g-parm.rst | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst new file mode 100644 index 000000000000..7116e0decddc --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst @@ -0,0 +1,349 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_G_PARM: + +********************************** +ioctl VIDIOC_G_PARM, VIDIOC_S_PARM +********************************** + +Name +==== + +VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters + + +Synopsis +======== + +.. cpp: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 :ref:`read() <func-read>` or +:ref:`write() <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 +:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a +pointer to a struct :ref:`struct v4l2_streamparm <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 :ref:`write() <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 :ref:`read() <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. |