diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-g-parm.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-g-parm.rst | 413 |
1 files changed, 163 insertions, 250 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst index 7116e0decddc..3b2e6e59a334 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-parm.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst @@ -15,7 +15,11 @@ VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters Synopsis ======== -.. cpp:function:: int ioctl( int fd, int request, v4l2_streamparm *argp ) +.. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp ) + :name: VIDIOC_G_PARM + +.. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp ) + :name: VIDIOC_S_PARM Arguments @@ -24,9 +28,6 @@ Arguments ``fd`` File descriptor returned by :ref:`open() <func-open>`. -``request`` - VIDIOC_G_PARM, VIDIOC_S_PARM - ``argp`` @@ -46,237 +47,157 @@ 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 +pointer to a struct :c:type:`v4l2_streamparm` which contains a union holding separate parameters for input and output devices. -.. _v4l2-streamparm: +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| + +.. c:type:: 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: + * - __u32 + - ``type`` + - + - The buffer (stream) type, same as struct + :c:type:`v4l2_format` ``type``, set by the + application. See :c:type:`v4l2_buf_type` + * - union + - ``parm`` + - + - + * - + - struct :c:type:`v4l2_captureparm` + - ``capture`` + - Parameters for capture devices, used when ``type`` is + ``V4L2_BUF_TYPE_VIDEO_CAPTURE``. + * - + - struct :c:type:`v4l2_outputparm` + - ``output`` + - Parameters for output devices, used when ``type`` is + ``V4L2_BUF_TYPE_VIDEO_OUTPUT``. + * - + - __u8 + - ``raw_data``\ [200] + - A place holder for future extensions. + + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: 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: + * - __u32 + - ``capability`` + - See :ref:`parm-caps`. + * - __u32 + - ``capturemode`` + - Set by drivers and applications, see :ref:`parm-flags`. + * - struct :c:type:`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 :c:type:`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. + * - __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`. + * - __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`. + * - __u32 + - ``reserved``\ [4] + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: 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. - - + * - __u32 + - ``capability`` + - See :ref:`parm-caps`. + * - __u32 + - ``outputmode`` + - Set by drivers and applications, see :ref:`parm-flags`. + * - struct :c:type:`v4l2_fract` + - ``timeperframe`` + - This is the desired period between successive frames output by the + driver, in seconds. + * - :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 :c:type:`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. + * - __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`. + * - __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`. + * - __u32 + - ``reserved``\ [4] + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _parm-caps: @@ -285,17 +206,14 @@ union holding separate parameters for input and output devices. :stub-columns: 0 :widths: 3 1 4 + * - ``V4L2_CAP_TIMEPERFRAME`` + - 0x1000 + - The frame skipping/repeating controlled by the ``timeperframe`` + field is supported. - - .. row 1 - - - ``V4L2_CAP_TIMEPERFRAME`` - - - 0x1000 - - - The frame skipping/repeating controlled by the ``timeperframe`` - field is supported. +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _parm-flags: @@ -304,41 +222,36 @@ union holding separate parameters for input and output devices. :stub-columns: 0 :widths: 3 1 4 + * - ``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: - - .. 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 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 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 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. + - 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. + - An image capture operation may be significantly slower than + motion capture. - - Moving objects in the image might have excessive motion blur. + - Moving objects in the image might have excessive motion blur. - - Capture might only work through the :ref:`read() <func-read>` call. + - Capture might only work through the :ref:`read() <func-read>` call. Return Value |